trezor-firmware/protob/messages-management.proto

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
}