mirror of
https://github.com/trezor/trezor-firmware.git
synced 2024-12-16 11:28:14 +00:00
401 lines
13 KiB
Protocol Buffer
401 lines
13 KiB
Protocol Buffer
syntax = "proto2";
|
|
|
|
// Sugar for easier handling in Java
|
|
option java_package = "com.satoshilabs.trezor.lib.protobuf";
|
|
option java_outer_classname = "TrezorMessageManagement";
|
|
|
|
import "common.proto";
|
|
|
|
/**
|
|
* Request: Reset device to default state and ask for device details
|
|
* @next Features
|
|
*/
|
|
message Initialize {
|
|
optional bytes state = 1; // assumed device state, clear session if set and different
|
|
optional bool skip_passphrase = 2; // this session should always assume empty passphrase
|
|
}
|
|
|
|
/**
|
|
* Request: Ask for device details (no device reset)
|
|
* @next Features
|
|
*/
|
|
message GetFeatures {
|
|
}
|
|
|
|
/**
|
|
* Response: Reports various information about the device
|
|
* @prev Initialize
|
|
* @prev GetFeatures
|
|
*/
|
|
message Features {
|
|
optional string vendor = 1; // name of the manufacturer, e.g. "trezor.io"
|
|
optional uint32 major_version = 2; // major version of the firmware/bootloader, e.g. 1
|
|
optional uint32 minor_version = 3; // minor version of the firmware/bootloader, e.g. 0
|
|
optional uint32 patch_version = 4; // patch version of the firmware/bootloader, 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
|
|
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
|
|
optional bool imported = 15; // was storage imported from an external source?
|
|
optional bool pin_cached = 16; // is PIN already cached in session?
|
|
optional bool passphrase_cached = 17; // is passphrase already cached in session?
|
|
optional bool firmware_present = 18; // is valid firmware loaded?
|
|
optional bool needs_backup = 19; // does storage need backup? (equals to Storage.needs_backup)
|
|
optional uint32 flags = 20; // device flags (equals to Storage.flags)
|
|
optional string model = 21; // device hardware model
|
|
optional uint32 fw_major = 22; // reported firmware version if in bootloader mode
|
|
optional uint32 fw_minor = 23; // reported firmware version if in bootloader mode
|
|
optional uint32 fw_patch = 24; // reported firmware version if in bootloader mode
|
|
optional string fw_vendor = 25; // reported firmware vendor if in bootloader mode
|
|
optional bytes fw_vendor_keys = 26; // reported firmware vendor keys (their hash)
|
|
optional bool unfinished_backup = 27; // report unfinished backup (equals to Storage.unfinished_backup)
|
|
}
|
|
|
|
/**
|
|
* Request: clear session (removes cached PIN, passphrase, etc).
|
|
* @next Success
|
|
*/
|
|
message ClearSession {
|
|
}
|
|
|
|
/**
|
|
* 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;
|
|
optional bool use_passphrase = 3;
|
|
optional bytes homescreen = 4;
|
|
optional PassphraseSourceType passphrase_source = 5;
|
|
optional uint32 auto_lock_delay_ms = 6;
|
|
/**
|
|
* Structure representing passphrase source
|
|
*/
|
|
enum PassphraseSourceType {
|
|
ASK = 0;
|
|
DEVICE = 1;
|
|
HOST = 2;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Request: set flags of the device
|
|
* @next Success
|
|
* @next Failure
|
|
*/
|
|
message ApplyFlags {
|
|
optional uint32 flags = 1; // bitmask, can only set bits, not unset
|
|
}
|
|
|
|
/**
|
|
* Request: Starts workflow for setting/changing/removing the PIN
|
|
* @next ButtonRequest
|
|
* @next PinMatrixRequest
|
|
*/
|
|
message ChangePin {
|
|
optional bool remove = 1; // is PIN removal requested?
|
|
}
|
|
|
|
/**
|
|
* Request: Test if the device is alive, device sends back the message in Success response
|
|
* @next Success
|
|
*/
|
|
message Ping {
|
|
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: Success of the previous request
|
|
*/
|
|
message Success {
|
|
optional string message = 1; // human readable description of action or request-specific payload
|
|
}
|
|
|
|
/**
|
|
* Response: Failure of the previous request
|
|
*/
|
|
message Failure {
|
|
optional FailureType code = 1; // computer-readable definition of the error state
|
|
optional string message = 2; // human-readable message of the error state
|
|
enum FailureType {
|
|
Failure_UnexpectedMessage = 1;
|
|
Failure_ButtonExpected = 2;
|
|
Failure_DataError = 3;
|
|
Failure_ActionCancelled = 4;
|
|
Failure_PinExpected = 5;
|
|
Failure_PinCancelled = 6;
|
|
Failure_PinInvalid = 7;
|
|
Failure_InvalidSignature = 8;
|
|
Failure_ProcessError = 9;
|
|
Failure_NotEnoughFunds = 10;
|
|
Failure_NotInitialized = 11;
|
|
Failure_PinMismatch = 12;
|
|
Failure_FirmwareError = 99;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Response: Device is waiting for HW button press.
|
|
* @next ButtonAck
|
|
* @next Cancel
|
|
*/
|
|
message ButtonRequest {
|
|
optional ButtonRequestType code = 1;
|
|
optional string data = 2;
|
|
/**
|
|
* Type of button request
|
|
*/
|
|
enum ButtonRequestType {
|
|
ButtonRequest_Other = 1;
|
|
ButtonRequest_FeeOverThreshold = 2;
|
|
ButtonRequest_ConfirmOutput = 3;
|
|
ButtonRequest_ResetDevice = 4;
|
|
ButtonRequest_ConfirmWord = 5;
|
|
ButtonRequest_WipeDevice = 6;
|
|
ButtonRequest_ProtectCall = 7;
|
|
ButtonRequest_SignTx = 8;
|
|
ButtonRequest_FirmwareCheck = 9;
|
|
ButtonRequest_Address = 10;
|
|
ButtonRequest_PublicKey = 11;
|
|
ButtonRequest_MnemonicWordCount = 12;
|
|
ButtonRequest_MnemonicInput = 13;
|
|
ButtonRequest_PassphraseType = 14;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Request: Computer agrees to wait for HW button press
|
|
* @prev ButtonRequest
|
|
*/
|
|
message ButtonAck {
|
|
}
|
|
|
|
/**
|
|
* 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;
|
|
/**
|
|
* Type of PIN request
|
|
*/
|
|
enum PinMatrixRequestType {
|
|
PinMatrixRequestType_Current = 1;
|
|
PinMatrixRequestType_NewFirst = 2;
|
|
PinMatrixRequestType_NewSecond = 3;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Request: Computer responds with encoded PIN
|
|
* @prev PinMatrixRequest
|
|
*/
|
|
message PinMatrixAck {
|
|
required string pin = 1; // matrix encoded PIN entered by user
|
|
}
|
|
|
|
/**
|
|
* Request: Abort last operation that required user interaction
|
|
* @prev ButtonRequest
|
|
* @prev PinMatrixRequest
|
|
* @prev PassphraseRequest
|
|
*/
|
|
message Cancel {
|
|
}
|
|
|
|
/**
|
|
* Response: Device awaits encryption passphrase
|
|
* @next PassphraseAck
|
|
* @next Cancel
|
|
*/
|
|
message PassphraseRequest {
|
|
optional bool on_device = 1; // passphrase is being entered on the device
|
|
}
|
|
|
|
/**
|
|
* Request: Send passphrase back
|
|
* @prev PassphraseRequest
|
|
* @next PassphraseStateRequest
|
|
*/
|
|
message PassphraseAck {
|
|
optional string passphrase = 1;
|
|
optional bytes state = 2; // expected device state
|
|
}
|
|
|
|
/**
|
|
* @prev PassphraseAck
|
|
* @next PassphraseStateAck
|
|
*/
|
|
message PassphraseStateRequest {
|
|
optional bytes state = 1; // actual device state
|
|
}
|
|
|
|
/**
|
|
* @prev PassphraseStateRequest
|
|
*/
|
|
message PassphraseStateAck {
|
|
}
|
|
|
|
/**
|
|
* 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 requested entropy
|
|
}
|
|
|
|
/**
|
|
* Response: Reply with random data generated by internal RNG
|
|
* @prev GetEntropy
|
|
*/
|
|
message Entropy {
|
|
required bytes entropy = 1; // chunk of random generated bytes
|
|
}
|
|
|
|
/**
|
|
* Request: Request device to wipe all sensitive data and settings
|
|
* @next ButtonRequest
|
|
*/
|
|
message WipeDevice {
|
|
}
|
|
|
|
/**
|
|
* 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 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
|
|
optional uint32 u2f_counter = 8; // U2F counter
|
|
}
|
|
|
|
/**
|
|
* Request: Ask device to do initialization involving user interaction
|
|
* @next EntropyRequest
|
|
* @next Failure
|
|
*/
|
|
message ResetDevice {
|
|
optional bool display_random = 1; // display entropy generated by the device before asking for additional entropy
|
|
optional uint32 strength = 2 [default=256]; // 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
|
|
optional uint32 u2f_counter = 7; // U2F counter
|
|
optional bool skip_backup = 8; // postpone seed backup to BackupDevice workflow
|
|
}
|
|
|
|
/**
|
|
* Request: Perform backup of the device seed if not backed up using ResetDevice
|
|
* @next ButtonRequest
|
|
*/
|
|
message BackupDevice {
|
|
}
|
|
|
|
/**
|
|
* Response: Ask for additional entropy from host computer
|
|
* @prev ResetDevice
|
|
* @next EntropyAck
|
|
*/
|
|
message EntropyRequest {
|
|
}
|
|
|
|
/**
|
|
* Request: Provide additional entropy for seed generation function
|
|
* @prev EntropyRequest
|
|
* @next ButtonRequest
|
|
*/
|
|
message EntropyAck {
|
|
optional bytes entropy = 1; // 256 bits (32 bytes) of random data
|
|
}
|
|
|
|
/**
|
|
* 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; // 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
|
|
// 7 reserved for unused recovery method
|
|
optional RecoveryDeviceType type = 8; // supported recovery type
|
|
optional uint32 u2f_counter = 9; // U2F counter
|
|
optional bool dry_run = 10; // perform dry-run recovery workflow (for safe mnemonic validation)
|
|
/**
|
|
* Type of recovery procedure. These should be used as bitmask, e.g.,
|
|
* `RecoveryDeviceType_ScrambledWords | RecoveryDeviceType_Matrix`
|
|
* listing every method supported by the host computer.
|
|
*
|
|
* Note that ScrambledWords must be supported by every implementation
|
|
* for backward compatibility; there is no way to not support it.
|
|
*/
|
|
enum RecoveryDeviceType {
|
|
// use powers of two when extending this field
|
|
RecoveryDeviceType_ScrambledWords = 0; // words in scrambled order
|
|
RecoveryDeviceType_Matrix = 1; // matrix recovery type
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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 {
|
|
optional WordRequestType type = 1;
|
|
/**
|
|
* Type of Recovery Word request
|
|
*/
|
|
enum WordRequestType {
|
|
WordRequestType_Plain = 0;
|
|
WordRequestType_Matrix9 = 1;
|
|
WordRequestType_Matrix6 = 2;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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
|
|
}
|
|
|
|
/**
|
|
* Request: Set U2F counter
|
|
* @next Success
|
|
*/
|
|
message SetU2FCounter {
|
|
optional uint32 u2f_counter = 1; // counter
|
|
}
|