trezor-firmware/common/protob/messages-management.proto

syntax = "proto2";
package hw.trezor.messages.management;

// Sugar for easier handling in Java
option java_package = "com.satoshilabs.trezor.lib.protobuf";
option java_outer_classname = "TrezorMessageManagement";

import "options.proto";

option (include_in_bitcoin_only) = true;


/**
 * Type of the mnemonic backup given/received by the device during reset/recovery.
 */
enum BackupType {
    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
}

/**
 * Level of safety checks for unsafe actions like spending from invalid path namespace or setting high transaction fee.
 */
enum SafetyCheckLevel {
    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
}


/**
 * Format of the homescreen image
 */
enum HomescreenFormat {
    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
 */
message Initialize {
    optional bytes session_id = 1;     // assumed device session id; Trezor clears caches if it is different or empty
    optional bool _skip_passphrase = 2 [deprecated=true]; // removed as part of passphrase redesign
    optional bool derive_cardano = 3;  // whether to derive Cardano Icarus root keys in this session
}

/**
 * Request: Ask for device details (no device reset)
 * @start
 * @next Features
 */
message GetFeatures {
}

/**
 * Response: Reports various information about the device
 * @end
 */
message Features {
    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 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 [deprecated=true]; // is passphrase already cached in session?
    optional bool firmware_present = 18;        // is valid firmware loaded?
    optional 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 string fw_vendor = 25;             // reported firmware vendor if in bootloader mode
    // optional bytes fw_vendor_keys = 26;      // obsoleted, use fw_vendor
    optional bool unfinished_backup = 27;       // report unfinished backup (equals to Storage.unfinished_backup)
    optional bool no_backup = 28;               // report no backup (equals to Storage.no_backup)
    optional RecoveryStatus recovery_status = 29;  // whether or not we are in recovery mode and of what kind
    repeated 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 namespace enforcement
    optional uint32 auto_lock_delay_ms = 38;    // number of milliseconds after which the device locks itself
    optional uint32 display_rotation = 39;      // 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 [default=true];  // 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. NB: this works in conjunction with recovery_status
    optional uint32 optiga_sec = 54;            // Optiga's security event counter.

    enum BackupAvailability {
        /// Device is already backed up, or a previous backup has failed.
        NotAvailable = 0;
        /// Device is not backed up. Backup is required.
        Required = 1;
        /// Device is already backed up and can be backed up again.
        Available = 2;
    }

    enum RecoveryStatus {
        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
    }

    enum Capability {
        option (has_bitcoin_only_values) = true;

        Capability_Bitcoin = 1 [(bitcoin_only) = true];
        Capability_Bitcoin_like = 2;                    // Altcoins based on the Bitcoin source code
        Capability_Binance = 3;
        Capability_Cardano = 4;
        Capability_Crypto = 5 [(bitcoin_only) = true];  // generic crypto operations for GPG, SSH, etc.
        Capability_EOS = 6;
        Capability_Ethereum = 7;
        Capability_Lisk = 8 [deprecated = true];
        Capability_Monero = 9;
        Capability_NEM = 10;
        Capability_Ripple = 11;
        Capability_Stellar = 12;
        Capability_Tezos = 13;
        Capability_U2F = 14;
        Capability_Shamir = 15 [(bitcoin_only) = true];
        Capability_ShamirGroups = 16 [(bitcoin_only) = true];
        Capability_PassphraseEntry = 17 [(bitcoin_only) = true];  // the device is capable of passphrase entry directly on the device
        Capability_Solana = 18;
        Capability_Translations = 19 [(bitcoin_only) = true];
        Capability_Brightness = 20 [(bitcoin_only) = true];
        Capability_Haptic = 21 [(bitcoin_only) = true];
    }
}

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

/**
 * Request: Show a "Do not disconnect" dialog instead of the standard homescreen.
 * @start
 * @next Success
 */
message SetBusy {
    optional uint32 expiry_ms = 1;  // The time in milliseconds after which the dialog will automatically disappear. Overrides any previously set expiry. If not set, then the dialog is hidden.
}

/**
 * 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 EndSession {
}

/**
 * Request: change some property of the device, e.g. label or homescreen
 * @start
 * @next Success
 * @next Failure
 */
message ApplySettings {
    optional string language = 1 [deprecated=true];
    optional string label = 2;
    optional bool use_passphrase = 3;
    optional bytes homescreen = 4;
    optional uint32 _passphrase_source = 5 [deprecated=true];   // ASK = 0; DEVICE = 1; HOST = 2;
    optional uint32 auto_lock_delay_ms = 6;
    optional uint32 display_rotation = 7;  // 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, set to Prompt to limit path namespace enforcement
    optional bool experimental_features = 10;  // 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
}

/**
 * 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 TranslationDataRequest
 * @next Failure
 */
message ChangeLanguage {
    // byte length of the whole translation blob (set to 0 for default language - english)
    required uint32 data_length = 1;
    // 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.
    optional bool show_display = 2;
}

/**
 * Response: Device asks for more data from transaction payload.
 * @end
 * @next TranslationDataAck
 */
 message TranslationDataRequest {
    required uint32 data_length = 1;    // Number of bytes being requested
    required uint32 data_offset = 2;    // Offset of the first byte being requested
}

/**
 * Request: Translation payload data.
 * @next TranslationDataRequest
 * @next Success
 */
message TranslationDataAck {
    required bytes data_chunk = 1;  // Bytes from translation payload
}

/**
 * Request: set flags of the device
 * @start
 * @next Success
 * @next Failure
 */
message ApplyFlags {
    required uint32 flags = 1;  // bitmask, can only set bits, not unset
}

/**
 * Request: Starts workflow for setting/changing/removing the PIN
 * @start
 * @next Success
 * @next Failure
 */
message ChangePin {
    optional bool remove = 1;   // is PIN removal requested?
}

/**
 * Request: Starts workflow for setting/removing the wipe code
 * @start
 * @next Success
 * @next Failure
 */
message ChangeWipeCode {
    optional bool remove = 1;   // is wipe code removal requested?
}

/**
 * Request: Starts workflow for enabling/regenerating/disabling SD card protection
 * @start
 * @next Success
 * @next Failure
 */
message SdProtect {
    required SdProtectOperationType operation = 1;
    /**
    * Structure representing SD card protection operation
    */
    enum SdProtectOperationType {
        DISABLE = 0;
        ENABLE = 1;
        REFRESH = 2;
    }
}

/**
 * Request: Test if the device is alive, device sends back the message in Success response
 * @start
 * @next Success
 */
message Ping {
    optional string message = 1 [default=""];   // message to send back in Success message
    optional bool button_protection = 2;        // ask for button press
}

/**
 * Request: Abort last operation that required user interaction
 * @start
 * @next Failure
 */
message Cancel {
}

/**
 * Request: Request a sample of random data generated by hardware RNG. May be used for testing.
 * @start
 * @next Entropy
 * @next Failure
 */
message GetEntropy {
    required uint32 size = 1;       // size of requested entropy
}

/**
 * Response: Reply with random data generated by internal RNG
 * @end
 */
message Entropy {
    required bytes entropy = 1;     // chunk of random generated bytes
}

/**
 * Request: Get a hash of the installed firmware combined with an optional challenge.
 * @start
 * @next FirmwareHash
 * @next Failure
 */
message GetFirmwareHash {
    optional bytes challenge = 1;   // Blake2s key up to 32 bytes in length.
}

/**
 * Response: Hash of the installed firmware combined with the optional challenge.
 * @end
 */
message FirmwareHash {
    required bytes hash = 1;
}

/**
 * Request: Request a signature of the provided challenge.
 * @start
 * @next AuthenticityProof
 * @next Failure
 */
message AuthenticateDevice {
    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
 */
message AuthenticityProof {
    repeated bytes certificates = 1;  // A certificate chain starting with the device certificate, followed by intermediate CA certificates, the last of which is signed by Trezor company's root CA.
    required bytes signature = 2;     // A DER-encoded signature of "\0x13AuthenticateDevice:" + length-prefixed challenge that should be verified using the device certificate.
}

/**
 * Request: Request device to wipe all sensitive data and settings
 * @start
 * @next Success
 * @next Failure
 */
message WipeDevice {
}

/**
 * Request: Load seed and related internal settings from the computer
 * @start
 * @next Success
 * @next Failure
 */
message LoadDevice {
    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=true];         // 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
}

/**
 * Request: Ask device to do initialization involving user interaction
 * @start
 * @next EntropyRequest
 * @next Failure
 */
message ResetDevice {
    reserved 1;                                             // unused display_random
    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 [deprecated=true];         // 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 [default=Bip39];   // type of the mnemonic backup
}

/**
 * Request: Perform backup of the device seed if not backed up using ResetDevice
 * @start
 * @next Success
 */
message BackupDevice {
    optional uint32 group_threshold = 1;
    message Slip39Group {
        required uint32 member_threshold = 1;
        required uint32 member_count = 2;
    }
    repeated Slip39Group groups = 2;
}

/**
 * Response: Ask for additional entropy from host computer
 * @next EntropyAck
 */
message EntropyRequest {
}

/**
 * Request: Provide additional entropy for seed generation function
 * @next Success
 */
message EntropyAck {
    required 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.
 * @start
 * @next WordRequest
 */
message RecoveryDevice {
    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=true];           // deprecated (use ChangeLanguage)
    optional string label = 5;                                // device label
    optional bool enforce_wordlist = 6;                       // enforce BIP-39 wordlist during the process (T1 only)
    reserved 7;                                               // unused recovery method
    optional RecoveryDeviceInputMethod input_method = 8;      // supported recovery input method (T1 only)
    optional uint32 u2f_counter = 9;                          // U2F counter
    optional RecoveryType type = 10 [default=NormalRecovery]; // 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.
     */
    enum RecoveryDeviceInputMethod {
        // use powers of two when extending this field
        ScrambledWords = 0;        // words in scrambled order
        Matrix = 1;                // matrix recovery type
    }
}

enum RecoveryType {
    NormalRecovery = 0;          // recovery from seedphrase on an uninitialized device
    DryRun = 1;                  // mnemonic validation
    UnlockRepeatedBackup = 2;    // unlock SLIP-39 repeated backup
}

/**
 * Response: Device is waiting for user to enter word of the mnemonic
 * Its position is shown only on device's internal display.
 * @next WordAck
 */
message WordRequest {
    required 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
 * @next WordRequest
 * @next Success
 * @next Failure
 */
message WordAck {
    required string word = 1;           // one word of mnemonic on asked position
}

/**
 * Request: Set U2F counter
 * @start
 * @next Success
 */
message SetU2FCounter {
    required uint32 u2f_counter = 1;
}

/**
 * Request: Set U2F counter
 * @start
 * @next NextU2FCounter
 */
message GetNextU2FCounter {
}

/**
 * Request: Set U2F counter
 * @end
 */
message NextU2FCounter {
    required uint32 u2f_counter = 1;
}

/**
 * Request: Ask device to prepare for a preauthorized operation.
 * @start
 * @next PreauthorizedRequest
 * @next Failure
 */
message DoPreauthorized {
}

/**
 * Request: Device awaits a preauthorized operation.
 * @start
 * @next SignTx
 * @next GetOwnershipProof
 */
message PreauthorizedRequest {
}

/**
 * Request: Cancel any outstanding authorization in the current session.
 * @start
 * @next Success
 * @next Failure
 */
message CancelAuthorization {
}

/**
 * Request: Reboot firmware to bootloader
 * @start
 * @next Success
 */
message RebootToBootloader {
    // Action to be performed after rebooting to bootloader
    optional BootCommand boot_command = 1 [default=STOP_AND_WAIT];
    // Firmware header to be flashed after rebooting to bootloader
    optional bytes firmware_header = 2;
    // Length of language blob to be installed before upgrading firmware
    optional uint32 language_data_length = 3 [default=0];

    enum BootCommand {
        // Go to bootloader menu
        STOP_AND_WAIT = 0;
        // Connect to host and wait for firmware update
        INSTALL_UPGRADE = 1;
    }
}

/**
 * Request: Ask device to generate a random nonce and store it in the session's cache
 * @start
 * @next Nonce
 */
message GetNonce {
    option (experimental_message) = true;
}

/**
 * Response: Contains a random nonce
 * @end
 */
message Nonce {
    option (experimental_message) = true;

    required bytes nonce = 1; // a 32-byte random value generated by Trezor
}

/**
 * Request: Ask device to unlock a subtree of the keychain.
 * @start
 * @next UnlockedPathRequest
 * @next Failure
 */
message UnlockPath {
    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
 */
message UnlockedPathRequest {
    optional bytes mac = 1;            // authentication code for future UnlockPath calls
}

/**
 * Request: Show tutorial screens on the device
 * @start
 * @next Success
 */
message ShowDeviceTutorial {
}

/**
 * Request: Unlocks bootloader, !irreversible!
 * @start
 * @next Success
 * @next Failure
 */
message UnlockBootloader {
}

/**
 * Request: Set device brightness
 * @start
 * @next Success
 */
message SetBrightness {
    optional uint32 value = 1;  // if not specified, let the user choose
}