package hw.trezor.messages.management

Get desktop application:
View/edit binary Protocol Buffers messages

* Request: set flags of the device @start @next Success @next Failure

• required uint32 flags = 1

  bitmask, can only set bits, not unset

* Request: change some property of the device, e.g. label or homescreen @start @next Success @next DataChunkRequest @next Failure

• optional string language = 1

• optional string label = 2

• optional bool use_passphrase = 3

• optional bytes homescreen = 4

  homescreen image in single array, deprecated for 14

• optional uint32 _passphrase_source = 5

  ASK = 0; DEVICE = 1; HOST = 2;

• optional uint32 auto_lock_delay_ms = 6

• optional DisplayRotation display_rotation = 7

  rotation of display (in degrees from North)

• optional bool passphrase_always_on_device = 8

  do not prompt for passphrase, enforce device entry

• optional SafetyCheckLevel safety_checks = 9

  Safety check level,

• optional bool experimental_features = 10

  set to Prompt to limit path namespace enforcement

  enable experimental message types

• optional bool hide_passphrase_from_host = 11

  do not show passphrase coming from host

• optional bool haptic_feedback = 13

  enable haptic feedback

• optional uint32 homescreen_length = 14

  byte length of new homescreen, device will request chunks

• optional uint32 auto_lock_delay_battery_ms = 15

  time in ms after which device locks when on battery

* Request: Request a signature of the provided challenge. @start @next AuthenticityProof @next Failure

• required bytes challenge = 1

  A random challenge to sign.

* Response: Signature of the provided challenge along with a certificate issued by the Trezor company. @end

• repeated bytes optiga_certificates = 1

  A certificate chain starting with the Optiga device certificate,

• required bytes optiga_signature = 2

  followed by intermediate CA certificates, the last of which is signed by Trezor company's root CA.

  A DER-encoded signature of "\x13AuthenticateDevice:" + length-prefixed

• repeated bytes tropic_certificates = 3

  challenge that should be verified using the Optiga device certificate.

  A certificate chain starting with the Tropic device certificate,

• optional bytes tropic_signature = 4

  followed by intermediate CA certificates, the last of which is signed by Trezor company's root CA.

  A DER-encoded signature of "\x13AuthenticateDevice:" + length-prefixed

* Request: Perform backup of the device seed if not backed up using ResetDevice @start @next Success

• optional uint32 group_threshold = 1

• repeated BackupDevice.Slip39Group groups = 2

Used in: BackupDevice

• required uint32 member_threshold = 1

• required uint32 member_count = 2

* Type of the mnemonic backup given/received by the device during reset/recovery.

Used in: debug.DebugLinkState, Features, ResetDevice

• Bip39 = 0

  also called "Single Backup", see BIP-0039

• Slip39_Basic = 1

  also called "Shamir Backup", see SLIP-0039

• Slip39_Advanced = 2

  also called "Super Shamir" or "Shamir with Groups", see SLIP-0039#two-level-scheme

• Slip39_Single_Extendable = 3

  extendable single-share Shamir backup

• Slip39_Basic_Extendable = 4

  extendable multi-share Shamir backup

• Slip39_Advanced_Extendable = 5

  extendable multi-share Shamir backup with groups

* Request: Abort last operation that required user interaction @start @next Failure

(message has no fields)

* Request: Cancel any outstanding authorization in the current session. @start @next Success @next Failure

(message has no fields)

* Request: change the device language via translation data. Does not send the translation data itself, as they are too large for one message. Device will request the translation data in chunks. @start @next DataChunkRequest @next Failure

• required uint32 data_length = 1

  byte length of the whole translation blob (set to 0 for default language - english)

• optional bool show_display = 2

  Prompt the user on screen. In certain conditions (such as freshly installed device), the confirmation prompt is not mandatory. Setting show_display=false will skip the prompt if that's the case. If the device does not allow skipping the prompt, a request with show_display=false will return a failure. (This way the host can safely try to change the language without invoking a prompt.) Setting show_display to true will always show the prompt. Leaving the option unset will show the prompt only when necessary.

* Request: Starts workflow for setting/changing/removing the PIN @start @next Success @next Failure

• optional bool remove = 1

  is PIN removal requested?

* Request: Starts workflow for setting/removing the wipe code @start @next Success @next Failure

• optional bool remove = 1

  is wipe code removal requested?

* Request: Translation/homescreen payload data. @next DataChunkRequest @next Success

• required bytes data_chunk = 1

  Bytes from translation/homescreen payload

* Response: Device asks for more data from translation/homescreen image. @end @next DataChunkAck

• required uint32 data_length = 1

  Number of bytes being requested

• required uint32 data_offset = 2

  Offset of the first byte being requested

* Allowed display rotation angles (in degrees from North)

Used in: ApplySettings, Features

• North = 0

• East = 90

• South = 180

• West = 270

* Request: Ask device to prepare for a preauthorized operation. @start @next PreauthorizedRequest @next Failure

(message has no fields)

* Request: end the current sesson. Following actions must call Initialize again. Cache for the current session is discarded, other sessions remain intact. Device is not PIN-locked. @start @next Success

(message has no fields)

* Response: Reply with random data generated by internal RNG @end

• required bytes entropy = 1

  chunk of random generated bytes

* Request: Provide additional entropy for seed generation function @next Success @next EntropyCheckReady

• required bytes entropy = 1

  256 bits (32 bytes) of the host's random data

* Request: Proceed with the next phase of the entropy check protocol, asking Trezor to either reveal its internal entropy or to finish and store the seed. @next Success @next EntropyRequest

• optional bool finish = 1

  finish the entropy check protocol, store the seed

* Response: Trezor is ready for the next phase of the entropy check protocol. @next EntropyCheckContinue @next GetPublicKey

(message has no fields)

* Response: Ask for additional entropy from host computer @next EntropyAck

• optional bytes entropy_commitment = 1

  HMAC-SHA256 of Trezor's internal entropy used in entropy check.

• optional bytes prev_entropy = 2

  Trezor's internal entropy from the previous round of entropy check.

* Response: Reports various information about the device @end

• optional string vendor = 1

  name of the manufacturer, e.g. "trezor.io"

• required uint32 major_version = 2

  major version of the firmware/bootloader, e.g. 1

• required uint32 minor_version = 3

  minor version of the firmware/bootloader, e.g. 0

• required uint32 patch_version = 4

  patch version of the firmware/bootloader, e.g. 0

• optional uint32 build_version = 61

  build 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 unlocked = 16

  is the device unlocked? called "pin_cached" previously

• optional bool _passphrase_cached = 17

  is passphrase already cached in session?

• optional bool firmware_present = 18

  is firmware loaded?

• optional Features.BackupAvailability backup_availability = 19

  does storage need backup? is repeated backup unlocked?

• 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 uint32 fw_build = 62

  reported firmware version if in bootloader mode

• optional string fw_vendor = 25

  reported firmware vendor if in bootloader mode

• optional bool unfinished_backup = 27

  optional bytes fw_vendor_keys = 26; // obsoleted, use fw_vendor

  report unfinished backup (equals to Storage.unfinished_backup)

• optional bool no_backup = 28

  report no backup (equals to Storage.no_backup)

• optional Features.RecoveryStatus recovery_status = 29

  whether or not we are in recovery mode and of what kind

• repeated Features.Capability capabilities = 30

  list of supported capabilities

• optional BackupType backup_type = 31

  type of device backup (BIP-39 / SLIP-39 basic / SLIP-39 advanced)

• optional bool sd_card_present = 32

  is SD card present

• optional bool sd_protection = 33

  is SD Protect enabled

• optional bool wipe_code_protection = 34

  is wipe code protection enabled

• optional bytes session_id = 35

• optional bool passphrase_always_on_device = 36

  device enforces passphrase entry on Trezor

• optional SafetyCheckLevel safety_checks = 37

  safety check level, set to Prompt to limit path

• optional uint32 auto_lock_delay_ms = 38

  namespace enforcement

  number of milliseconds after which the device locks itself

• optional DisplayRotation display_rotation = 39

  rotation of display (in degrees from North)

• optional bool experimental_features = 40

  are experimental message types enabled?

• optional bool busy = 41

  is the device busy, showing "Do not disconnect"?

• optional HomescreenFormat homescreen_format = 42

  format of the homescreen, 1 = TOIf, 2 = jpg, 3 = TOIG

• optional bool hide_passphrase_from_host = 43

  should we hide the passphrase when it comes from host?

• optional string internal_model = 44

  internal model name

• optional uint32 unit_color = 45

  color of the unit/device

• optional bool unit_btconly = 46

  unit/device is intended as bitcoin only

• optional uint32 homescreen_width = 47

  homescreen width in pixels

• optional uint32 homescreen_height = 48

  homescreen height in pixels

• optional bool bootloader_locked = 49

  bootloader is locked

• optional bool language_version_matches = 50

  translation blob version matches firmware version

• optional uint32 unit_packaging = 51

  unit/device packaging version

• optional bool haptic_feedback = 52

  haptic feedback is enabled

• optional RecoveryType recovery_type = 53

  what type of recovery we are in

• optional uint32 optiga_sec = 54

  NB: this works in conjunction with recovery_status

  Optiga's security event counter.

• optional uint32 soc = 55

  Battery state of charge (0 - 100%)

• optional bool firmware_corrupted = 56

  true if the firmware is corrupted

• optional uint32 auto_lock_delay_battery_ms = 57

  number of milliseconds after which

• optional bool led = 58

  the battery-powered device locks itself

  RGB LED settings

• optional bool usb_connected = 59

  USB connected

• optional bool wireless_connected = 60

  Wireless charger connected

Used in: Features

• NotAvailable = 0

  / Device is already backed up, or a previous backup has failed.

• Required = 1

  / Device is not backed up. Backup is required.

• Available = 2

  / Device is already backed up and can be backed up again.

Used in: Features

• Capability_Bitcoin = 1

• Capability_Bitcoin_like = 2

  Altcoins based on the Bitcoin source code

• Capability_Binance = 3

  BNB Smart Chain

• Capability_Cardano = 4

• Capability_Crypto = 5

  generic crypto operations for GPG, SSH, etc.

• Capability_EOS = 6

• Capability_Ethereum = 7

• Capability_Lisk = 8

• Capability_Monero = 9

• Capability_NEM = 10

• Capability_Ripple = 11

• Capability_Stellar = 12

• Capability_Tezos = 13

• Capability_U2F = 14

• Capability_Shamir = 15

• Capability_ShamirGroups = 16

• Capability_PassphraseEntry = 17

  the device is capable of passphrase entry

• Capability_Solana = 18

  directly on the device

• Capability_Translations = 19

• Capability_Brightness = 20

• Capability_Haptic = 21

• Capability_BLE = 22

  Bluetooth Low Energy

• Capability_NFC = 23

  Near Field Communications

• Capability_Tron = 24

Used in: Features

• Nothing = 0

  we are not in recovery mode

• Recovery = 1

  we are in "Normal" or "DryRun" recovery

• Backup = 2

  we are in repeated backup mode

* Response: Hash of the installed firmware combined with the optional challenge. @end

• required bytes hash = 1

* Request: Request a sample of random data generated by hardware RNG. May be used for testing. @start @next Entropy @next Failure

• required uint32 size = 1

  size of requested entropy

* Request: Ask for device details (no device reset) @start @next Features

(message has no fields)

* Request: Get a hash of the installed firmware combined with an optional challenge. @start @next FirmwareHash @next Failure

• optional bytes challenge = 1

  Blake2s key up to 32 bytes in length.

* Request: Set U2F counter @start @next NextU2FCounter

(message has no fields)

* Request: Ask device to generate a random nonce and store it in the session's cache @start @next Nonce

(message has no fields)

* Request: Get unit serial number @start @next SerialNumber

(message has no fields)

* Format of the homescreen image

Used in: Features

• Toif = 1

  full-color toif

• Jpeg = 2

  jpeg

• ToiG = 3

  greyscale toif

* Request: Reset device to default state and ask for device details @start @next Features

• optional bytes session_id = 1

  assumed device session id; Trezor clears caches if it is different or empty

• optional bool _skip_passphrase = 2

  removed as part of passphrase redesign

• optional bool derive_cardano = 3

  whether to derive Cardano Icarus root keys in this session

* Request: Load seed and related internal settings from the computer @start @next Success @next Failure

• repeated string mnemonics = 1

  seed encoded as mnemonic (12, 18 or 24 words for BIP39, 20 or 33 for SLIP39)

• optional string pin = 3

  set PIN protection

• optional bool passphrase_protection = 4

  enable master node encryption using passphrase

• optional string language = 5

  deprecated (use ChangeLanguage)

• 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

• optional bool needs_backup = 9

  set "needs backup" flag

• optional bool no_backup = 10

  indicate that no backup is going to be made

• optional bool unfinished_backup = 11

  indicate that backup process has failed

* Request: soft-lock the device. Following actions will require PIN. Passphrases remain cached. @start @next Success

(message has no fields)

* Request: Set U2F counter @end

• required uint32 u2f_counter = 1

* Response: Contains a random nonce @end

• required bytes nonce = 1

  a 32-byte random value generated by Trezor

* Request: Test if the device is alive, device sends back the message in Success response @start @next Success

• optional string message = 1

  message to send back in Success message

• optional bool button_protection = 2

  ask for button press

* Request: Device awaits a preauthorized operation. @start @next SignTx @next GetOwnershipProof

(message has no fields)

* Request: Reboot firmware to bootloader @start @next Success @next DataChunkRequest

• optional RebootToBootloader.BootCommand boot_command = 1

  Action to be performed after rebooting to bootloader

• optional bytes firmware_header = 2

  Firmware header to be flashed after rebooting to bootloader

Used in: RebootToBootloader

• STOP_AND_WAIT = 0

  Go to bootloader menu

• INSTALL_UPGRADE = 1

  Connect to host and wait for firmware update

* Request: Start recovery workflow asking user for specific words of mnemonic Used to recovery device safely even on untrusted computer. @start @next WordRequest

• optional uint32 word_count = 1

  number of words in BIP-39 mnemonic (T1 only)

• optional bool passphrase_protection = 2

  enable master node encryption using passphrase

• optional bool pin_protection = 3

  enable PIN protection

• optional string language = 4

  deprecated (use ChangeLanguage)

• optional string label = 5

  device label

• optional bool enforce_wordlist = 6

  enforce BIP-39 wordlist during the process (T1 only)

• optional RecoveryDevice.RecoveryDeviceInputMethod input_method = 8

  supported recovery input method (T1 only)

• optional uint32 u2f_counter = 9

  U2F counter

• optional RecoveryType type = 10

  the type of recovery to perform

* Type of recovery procedure. These should be used as bitmask, e.g., `RecoveryDeviceInputMethod_ScrambledWords | RecoveryDeviceInputMethod_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.

Used in: RecoveryDevice

• ScrambledWords = 0

  use powers of two when extending this field

  words in scrambled order

• Matrix = 1

  matrix recovery type

Used in: Features, RecoveryDevice

• NormalRecovery = 0

  recovery from seedphrase on an uninitialized device

• DryRun = 1

  mnemonic validation

• UnlockRepeatedBackup = 2

  unlock SLIP-39 repeated backup

* Request: Ask device to do initialization involving user interaction @start @next EntropyRequest @next Failure

• optional uint32 strength = 2

  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

  deprecated (use ChangeLanguage)

• optional string label = 6

  device label

• optional uint32 u2f_counter = 7

  U2F counter

• optional bool skip_backup = 8

  postpone seed backup to BackupDevice workflow

• optional bool no_backup = 9

  indicate that no backup is going to be made

• optional BackupType backup_type = 10

  type of the mnemonic backup

• optional bool entropy_check = 11

  run with entropy check protocol

* Level of safety checks for unsafe actions like spending from invalid path namespace or setting high transaction fee.

Used in: ApplySettings, Features

• Strict = 0

  disallow unsafe actions, this is the default

• PromptAlways = 1

  ask user before unsafe action

• PromptTemporarily = 2

  like PromptAlways but reverts to Strict after reboot

* Request: Starts workflow for enabling/regenerating/disabling SD card protection @start @next Success @next Failure

• required SdProtect.SdProtectOperationType operation = 1

* Structure representing SD card protection operation

Used in: SdProtect

• DISABLE = 0

• ENABLE = 1

• REFRESH = 2

* Response: contains unit serial number @end

• required string serial_number = 1

* Request: Set device brightness @start @next Success

• optional uint32 value = 1

  if not specified, let the user choose

* Request: Show a "Do not disconnect" dialog instead of the standard homescreen. @start @next Success

• optional uint32 expiry_ms = 1

  The time in milliseconds after which the dialog will automatically disappear.

* Request: Set U2F counter @start @next Success

• required uint32 u2f_counter = 1

* Request: Show tutorial screens on the device @start @next Success

(message has no fields)

* Request: Unlocks bootloader, !irreversible! @start @next Success @next Failure

(message has no fields)

* Request: Ask device to unlock a subtree of the keychain. @start @next UnlockedPathRequest @next Failure

• repeated uint32 address_n = 1

  prefix of the BIP-32 path leading to the account (m / purpose')

• optional bytes mac = 2

  the MAC returned by UnlockedPathRequest

* Request: Device awaits an operation. @start @next SignTx @next GetPublicKey @next GetAddress

• required bytes mac = 1

  authentication code for future UnlockPath calls

* Request: Request device to wipe all sensitive data and settings @start @next Success @next Failure

(message has no fields)

* Request: Computer replies with word from the mnemonic @next WordRequest @next Success @next Failure

• required string word = 1

  one word of mnemonic on asked position

* Response: Device is waiting for user to enter word of the mnemonic Its position is shown only on device's internal display. @next WordAck

• required WordRequest.WordRequestType type = 1

* Type of Recovery Word request

Used in: WordRequest

• WordRequestType_Plain = 0

• WordRequestType_Matrix9 = 1

• WordRequestType_Matrix6 = 2