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 AuthenticityProofSizes @next Failure

• required bytes challenge = 1

  A random challenge to sign.

• optional bool stream = 2

  If set, the certificates and signatures data is sent using a stream of

* 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

• repeated bytes mcu_certificates = 5

  challenge that should be verified using the Tropic device certificate.

  An MCU device certificate signed by Trezor company's root CA.

• optional bytes mcu_signature = 6

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

* Response: Return requested authenticity proof data chunk. @next GetAuthenticityProofChunk

• required bytes chunk = 1

* Response: Sizes of the corresponding proof parts (see above). @next GetAuthenticityProofChunk

• repeated uint32 optiga_certificates = 1

• required uint32 optiga_signature = 2

• repeated uint32 tropic_certificates = 3

• optional uint32 tropic_signature = 4

• repeated uint32 mcu_certificates = 5

• optional uint32 mcu_signature = 6

* 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

• optional BackupMethod backup_method = 3

  how the mnemonic shares should be backed up

Used in: BackupDevice

• required uint32 member_threshold = 1

• required uint32 member_count = 2

* Backup method of the mnemonic shares.

Used in: BackupDevice, RecoveryDevice, ResetDevice

• Display = 0

  the share words are displayed on the device screen

• N4W1 = 1

* 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

• optional bool tap_to_wake = 63

  tap to wake is enabled (None = not supported)

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

• Capability_N4W1 = 25

• Capability_TouchWakeup = 26

  Touch to wake from sleep

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 authenticity proof data chunk, or finish the workflow if `proof_type` is not set. @next AuthenticityProofChunk @next Success

• optional GetAuthenticityProofChunk.AuthenticityProofType proof_type = 1

  Specifies proof part to fetch.

• optional uint32 index = 2

  If set, certificates[index] is fetched. Otherwise, signature is fetched.

• required uint32 offset = 3

  Data chunk offset (in bytes).

• required uint32 size = 4

  Data chunk size (in bytes).

Used in: GetAuthenticityProofChunk

• OPTIGA = 0

• TROPIC = 1

• MCU = 2

* 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

• optional BackupMethod backup_method = 11

  how the shares should be recovered from backup

* 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 Matrix recovery is the recommended recovery method. ScrambledWords is allowed only for 24 word recovery, unless safety checks are disabled.

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

• optional BackupMethod backup_method = 12

  how the mnemonic shares should be backed up

* 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