github.com/zhiqiangxu/go-ethereum@v1.9.16-0.20210824055606-be91cfdebc48/accounts/usbwallet/trezor/messages-management.proto (about)

     1  // This file originates from the SatoshiLabs Trezor `common` repository at:
     2  //   https://github.com/trezor/trezor-common/blob/master/protob/messages-management.proto
     3  // dated 28.05.2019, commit 893fd219d4a01bcffa0cd9cfa631856371ec5aa9.
     4  
     5  syntax = "proto2";
     6  package hw.trezor.messages.management;
     7  
     8  // Sugar for easier handling in Java
     9  option java_package = "com.satoshilabs.trezor.lib.protobuf";
    10  option java_outer_classname = "TrezorMessageManagement";
    11  
    12  import "messages-common.proto";
    13  
    14  /**
    15   * Request: Reset device to default state and ask for device details
    16   * @start
    17   * @next Features
    18   */
    19  message Initialize {
    20      optional bytes state = 1;           // assumed device state, clear session if set and different
    21      optional bool skip_passphrase = 2;  // this session should always assume empty passphrase
    22  }
    23  
    24  /**
    25   * Request: Ask for device details (no device reset)
    26   * @start
    27   * @next Features
    28   */
    29  message GetFeatures {
    30  }
    31  
    32  /**
    33   * Response: Reports various information about the device
    34   * @end
    35   */
    36  message Features {
    37      optional string vendor = 1;                 // name of the manufacturer, e.g. "trezor.io"
    38      optional uint32 major_version = 2;          // major version of the firmware/bootloader, e.g. 1
    39      optional uint32 minor_version = 3;          // minor version of the firmware/bootloader, e.g. 0
    40      optional uint32 patch_version = 4;          // patch version of the firmware/bootloader, e.g. 0
    41      optional bool bootloader_mode = 5;          // is device in bootloader mode?
    42      optional string device_id = 6;              // device's unique identifier
    43      optional bool pin_protection = 7;           // is device protected by PIN?
    44      optional bool passphrase_protection = 8;    // is node/mnemonic encrypted using passphrase?
    45      optional string language = 9;               // device language
    46      optional string label = 10;                 // device description label
    47      optional bool initialized = 12;             // does device contain seed?
    48      optional bytes revision = 13;               // SCM revision of firmware
    49      optional bytes bootloader_hash = 14;        // hash of the bootloader
    50      optional bool imported = 15;                // was storage imported from an external source?
    51      optional bool pin_cached = 16;              // is PIN already cached in session?
    52      optional bool passphrase_cached = 17;       // is passphrase already cached in session?
    53      optional bool firmware_present = 18;        // is valid firmware loaded?
    54      optional bool needs_backup = 19;            // does storage need backup? (equals to Storage.needs_backup)
    55      optional uint32 flags = 20;                 // device flags (equals to Storage.flags)
    56      optional string model = 21;                 // device hardware model
    57      optional uint32 fw_major = 22;              // reported firmware version if in bootloader mode
    58      optional uint32 fw_minor = 23;              // reported firmware version if in bootloader mode
    59      optional uint32 fw_patch = 24;              // reported firmware version if in bootloader mode
    60      optional string fw_vendor = 25;             // reported firmware vendor if in bootloader mode
    61      optional bytes fw_vendor_keys = 26;         // reported firmware vendor keys (their hash)
    62      optional bool unfinished_backup = 27;       // report unfinished backup (equals to Storage.unfinished_backup)
    63      optional bool no_backup = 28;               // report no backup (equals to Storage.no_backup)
    64  }
    65  
    66  /**
    67   * Request: clear session (removes cached PIN, passphrase, etc).
    68   * @start
    69   * @next Success
    70   */
    71  message ClearSession {
    72  }
    73  
    74  /**
    75   * Request: change language and/or label of the device
    76   * @start
    77   * @next Success
    78   * @next Failure
    79   */
    80  message ApplySettings {
    81      optional string language = 1;
    82      optional string label = 2;
    83      optional bool use_passphrase = 3;
    84      optional bytes homescreen = 4;
    85      optional PassphraseSourceType passphrase_source = 5;
    86      optional uint32 auto_lock_delay_ms = 6;
    87      optional uint32 display_rotation = 7;  // in degrees from North
    88      /**
    89      * Structure representing passphrase source
    90      */
    91      enum PassphraseSourceType {
    92          ASK = 0;
    93          DEVICE = 1;
    94          HOST = 2;
    95      }
    96  }
    97  
    98  /**
    99   * Request: set flags of the device
   100   * @start
   101   * @next Success
   102   * @next Failure
   103   */
   104  message ApplyFlags {
   105      optional uint32 flags = 1;  // bitmask, can only set bits, not unset
   106  }
   107  
   108  /**
   109   * Request: Starts workflow for setting/changing/removing the PIN
   110   * @start
   111   * @next Success
   112   * @next Failure
   113   */
   114  message ChangePin {
   115      optional bool remove = 1;   // is PIN removal requested?
   116  }
   117  
   118  /**
   119   * Request: Test if the device is alive, device sends back the message in Success response
   120   * @start
   121   * @next Success
   122   */
   123  message Ping {
   124      optional string message = 1;                // message to send back in Success message
   125      optional bool button_protection = 2;        // ask for button press
   126      optional bool pin_protection = 3;           // ask for PIN if set in device
   127      optional bool passphrase_protection = 4;    // ask for passphrase if set in device
   128  }
   129  
   130  /**
   131   * Request: Abort last operation that required user interaction
   132   * @start
   133   * @next Failure
   134   */
   135  message Cancel {
   136  }
   137  
   138  /**
   139   * Request: Request a sample of random data generated by hardware RNG. May be used for testing.
   140   * @start
   141   * @next Entropy
   142   * @next Failure
   143   */
   144  message GetEntropy {
   145      required uint32 size = 1;       // size of requested entropy
   146  }
   147  
   148  /**
   149   * Response: Reply with random data generated by internal RNG
   150   * @end
   151   */
   152  message Entropy {
   153      required bytes entropy = 1;     // chunk of random generated bytes
   154  }
   155  
   156  /**
   157   * Request: Request device to wipe all sensitive data and settings
   158   * @start
   159   * @next Success
   160   * @next Failure
   161   */
   162  message WipeDevice {
   163  }
   164  
   165  /**
   166   * Request: Load seed and related internal settings from the computer
   167   * @start
   168   * @next Success
   169   * @next Failure
   170   */
   171  message LoadDevice {
   172      optional string mnemonic = 1;                           // seed encoded as BIP-39 mnemonic (12, 18 or 24 words)
   173      optional hw.trezor.messages.common.HDNodeType node = 2; // BIP-32 node
   174      optional string pin = 3;                                // set PIN protection
   175      optional bool passphrase_protection = 4;                // enable master node encryption using passphrase
   176      optional string language = 5 [default='english'];       // device language
   177      optional string label = 6;                              // device label
   178      optional bool skip_checksum = 7;                        // do not test mnemonic for valid BIP-39 checksum
   179      optional uint32 u2f_counter = 8;                        // U2F counter
   180  }
   181  
   182  /**
   183   * Request: Ask device to do initialization involving user interaction
   184   * @start
   185   * @next EntropyRequest
   186   * @next Failure
   187   */
   188  message ResetDevice {
   189      optional bool display_random = 1;                   // display entropy generated by the device before asking for additional entropy
   190      optional uint32 strength = 2 [default=256];         // strength of seed in bits
   191      optional bool passphrase_protection = 3;            // enable master node encryption using passphrase
   192      optional bool pin_protection = 4;                   // enable PIN protection
   193      optional string language = 5 [default='english'];   // device language
   194      optional string label = 6;                          // device label
   195      optional uint32 u2f_counter = 7;                    // U2F counter
   196      optional bool skip_backup = 8;                      // postpone seed backup to BackupDevice workflow
   197      optional bool no_backup = 9;                        // indicate that no backup is going to be made
   198  }
   199  
   200  /**
   201   * Request: Perform backup of the device seed if not backed up using ResetDevice
   202   * @start
   203   * @next Success
   204   */
   205  message BackupDevice {
   206  }
   207  
   208  /**
   209   * Response: Ask for additional entropy from host computer
   210   * @next EntropyAck
   211   */
   212  message EntropyRequest {
   213  }
   214  
   215  /**
   216   * Request: Provide additional entropy for seed generation function
   217   * @next Success
   218   */
   219  message EntropyAck {
   220      optional bytes entropy = 1;     // 256 bits (32 bytes) of random data
   221  }
   222  
   223  /**
   224   * Request: Start recovery workflow asking user for specific words of mnemonic
   225   * Used to recovery device safely even on untrusted computer.
   226   * @start
   227   * @next WordRequest
   228   */
   229  message RecoveryDevice {
   230      optional uint32 word_count = 1;                     // number of words in BIP-39 mnemonic
   231      optional bool passphrase_protection = 2;            // enable master node encryption using passphrase
   232      optional bool pin_protection = 3;                   // enable PIN protection
   233      optional string language = 4 [default='english'];   // device language
   234      optional string label = 5;                          // device label
   235      optional bool enforce_wordlist = 6;                 // enforce BIP-39 wordlist during the process
   236      // 7 reserved for unused recovery method
   237      optional RecoveryDeviceType type = 8;               // supported recovery type
   238      optional uint32 u2f_counter = 9;                    // U2F counter
   239      optional bool dry_run = 10;                         // perform dry-run recovery workflow (for safe mnemonic validation)
   240      /**
   241       * Type of recovery procedure. These should be used as bitmask, e.g.,
   242       * `RecoveryDeviceType_ScrambledWords | RecoveryDeviceType_Matrix`
   243       * listing every method supported by the host computer.
   244       *
   245       * Note that ScrambledWords must be supported by every implementation
   246       * for backward compatibility; there is no way to not support it.
   247       */
   248      enum RecoveryDeviceType {
   249          // use powers of two when extending this field
   250          RecoveryDeviceType_ScrambledWords = 0;        // words in scrambled order
   251          RecoveryDeviceType_Matrix = 1;                // matrix recovery type
   252      }
   253  }
   254  
   255  /**
   256   * Response: Device is waiting for user to enter word of the mnemonic
   257   * Its position is shown only on device's internal display.
   258   * @next WordAck
   259   */
   260  message WordRequest {
   261      optional WordRequestType type = 1;
   262      /**
   263      * Type of Recovery Word request
   264      */
   265      enum WordRequestType {
   266          WordRequestType_Plain = 0;
   267          WordRequestType_Matrix9 = 1;
   268          WordRequestType_Matrix6 = 2;
   269      }
   270  }
   271  
   272  /**
   273   * Request: Computer replies with word from the mnemonic
   274   * @next WordRequest
   275   * @next Success
   276   * @next Failure
   277   */
   278  message WordAck {
   279      required string word = 1;           // one word of mnemonic on asked position
   280  }
   281  
   282  /**
   283   * Request: Set U2F counter
   284   * @start
   285   * @next Success
   286   */
   287  message SetU2FCounter {
   288      optional uint32 u2f_counter = 1;    // counter
   289  }