1/* 2 * Messages for KeepKey Communication 3 * 4 */ 5 6syntax = "proto2"; 7 8// Sugar for easier handling in Java 9option java_package = "com.keepkey.deviceprotocol"; 10option java_outer_classname = "KeepKeyMessage"; 11 12import "types.proto"; 13 14/** 15 * Mapping between KeepKey wire identifier (uint) and a protobuf message 16 */ 17enum MessageType { 18 MessageType_Initialize = 0 [(wire_in) = true]; 19 MessageType_Ping = 1 [(wire_in) = true]; 20 MessageType_Success = 2 [(wire_out) = true]; 21 MessageType_Failure = 3 [(wire_out) = true]; 22 MessageType_ChangePin = 4 [(wire_in) = true]; 23 MessageType_WipeDevice = 5 [(wire_in) = true]; 24 MessageType_FirmwareErase = 6 [(wire_in) = true]; 25 MessageType_FirmwareUpload = 7 [(wire_in) = true]; 26 MessageType_GetEntropy = 9 [(wire_in) = true]; 27 MessageType_Entropy = 10 [(wire_out) = true]; 28 MessageType_GetPublicKey = 11 [(wire_in) = true]; 29 MessageType_PublicKey = 12 [(wire_out) = true]; 30 MessageType_LoadDevice = 13 [(wire_in) = true]; 31 MessageType_ResetDevice = 14 [(wire_in) = true]; 32 MessageType_SignTx = 15 [(wire_in) = true]; 33 // Formerly SimpleSignTx = 16 34 MessageType_Features = 17 [(wire_out) = true]; 35 MessageType_PinMatrixRequest = 18 [(wire_out) = true]; 36 MessageType_PinMatrixAck = 19 [(wire_in) = true]; 37 MessageType_Cancel = 20 [(wire_in) = true]; 38 MessageType_TxRequest = 21 [(wire_out) = true]; 39 MessageType_TxAck = 22 [(wire_in) = true]; 40 MessageType_CipherKeyValue = 23 [(wire_in) = true]; 41 MessageType_ClearSession = 24 [(wire_in) = true]; 42 MessageType_ApplySettings = 25 [(wire_in) = true]; 43 MessageType_ButtonRequest = 26 [(wire_out) = true]; 44 MessageType_ButtonAck = 27 [(wire_in) = true]; 45 MessageType_GetAddress = 29 [(wire_in) = true]; 46 MessageType_Address = 30 [(wire_out) = true]; 47 MessageType_EntropyRequest = 35 [(wire_out) = true]; 48 MessageType_EntropyAck = 36 [(wire_in) = true]; 49 MessageType_SignMessage = 38 [(wire_in) = true]; 50 MessageType_VerifyMessage = 39 [(wire_in) = true]; 51 MessageType_MessageSignature = 40 [(wire_out) = true]; 52 MessageType_PassphraseRequest = 41 [(wire_out) = true]; 53 MessageType_PassphraseAck = 42 [(wire_in) = true]; 54 // Formerly EstimateTxSize = 43 55 // Formerly TxSize = 44 56 MessageType_RecoveryDevice = 45 [(wire_in) = true]; 57 MessageType_WordRequest = 46 [(wire_out) = true]; 58 MessageType_WordAck = 47 [(wire_in) = true]; 59 MessageType_CipheredKeyValue = 48 [(wire_out) = true]; 60 MessageType_EncryptMessage = 49 [(wire_in) = true]; 61 MessageType_EncryptedMessage = 50 [(wire_out) = true]; 62 MessageType_DecryptMessage = 51 [(wire_in) = true]; 63 MessageType_DecryptedMessage = 52 [(wire_out) = true]; 64 MessageType_SignIdentity = 53 [(wire_in) = true]; 65 MessageType_SignedIdentity = 54 [(wire_out) = true]; 66 MessageType_GetFeatures = 55 [(wire_in) = true]; 67 MessageType_EthereumGetAddress = 56 [(wire_in) = true]; 68 MessageType_EthereumAddress = 57 [(wire_out) = true]; 69 MessageType_EthereumSignTx = 58 [(wire_in) = true]; 70 MessageType_EthereumTxRequest = 59 [(wire_out) = true]; 71 MessageType_EthereumTxAck = 60 [(wire_in) = true]; 72 MessageType_CharacterRequest = 80 [(wire_out) = true]; 73 MessageType_CharacterAck = 81 [(wire_in) = true]; 74 MessageType_RawTxAck = 82 [(wire_in) = true]; 75 MessageType_ApplyPolicies = 83 [(wire_in) = true]; 76 MessageType_FlashHash = 84 [(wire_in) = true]; 77 MessageType_FlashWrite = 85 [(wire_in) = true]; 78 MessageType_FlashHashResponse = 86 [(wire_out) = true]; 79 MessageType_DebugLinkFlashDump = 87 [(wire_debug_in) = true]; 80 MessageType_DebugLinkFlashDumpResponse = 88 [(wire_debug_out) = true]; 81 MessageType_SoftReset = 89 [(wire_debug_in) = true]; 82 MessageType_DebugLinkDecision = 100 [(wire_debug_in) = true]; 83 MessageType_DebugLinkGetState = 101 [(wire_debug_in) = true]; 84 MessageType_DebugLinkState = 102 [(wire_debug_out) = true]; 85 MessageType_DebugLinkStop = 103 [(wire_debug_in) = true]; 86 MessageType_DebugLinkLog = 104 [(wire_debug_out) = true]; 87 MessageType_DebugLinkFillConfig = 105 [(wire_debug_out) = true]; 88 MessageType_GetCoinTable = 106 [(wire_in) = true]; 89 MessageType_CoinTable = 107 [(wire_out) = true]; 90 MessageType_EthereumSignMessage = 108 [(wire_in) = true]; 91 MessageType_EthereumVerifyMessage = 109 [(wire_in) = true]; 92 MessageType_EthereumMessageSignature = 110 [(wire_out) = true]; 93 MessageType_ChangeWipeCode = 111 [(wire_in) = true]; 94 95 // Ripple 96 MessageType_RippleGetAddress = 400 [(wire_in) = true]; 97 MessageType_RippleAddress = 401 [(wire_out) = true]; 98 MessageType_RippleSignTx = 402 [(wire_in) = true]; 99 MessageType_RippleSignedTx = 403 [(wire_in) = true]; 100 101 // THORChain 102 MessageType_ThorchainGetAddress = 500 [(wire_in) = true]; 103 MessageType_ThorchainAddress = 501 [(wire_out) = true]; 104 MessageType_ThorchainSignTx = 502 [(wire_in) = true]; 105 MessageType_ThorchainMsgRequest = 503 [(wire_out) = true]; 106 MessageType_ThorchainMsgAck = 504 [(wire_in) = true]; 107 MessageType_ThorchainSignedTx = 505 [(wire_out) = true]; 108 109 // EOS 110 MessageType_EosGetPublicKey = 600 [(wire_in) = true]; 111 MessageType_EosPublicKey = 601 [(wire_out) = true]; 112 MessageType_EosSignTx = 602 [(wire_in) = true]; 113 MessageType_EosTxActionRequest = 603 [(wire_out) = true]; 114 MessageType_EosTxActionAck = 604 [(wire_in) = true]; 115 MessageType_EosSignedTx = 605 [(wire_out) = true]; 116 117 // Nano 118 MessageType_NanoGetAddress = 700 [(wire_in) = true]; 119 MessageType_NanoAddress = 701 [(wire_out) = true]; 120 MessageType_NanoSignTx = 702 [(wire_in) = true]; 121 MessageType_NanoSignedTx = 703 [(wire_out) = true]; 122 123 // Binance 124 MessageType_BinanceGetAddress = 800 [(wire_in) = true]; 125 MessageType_BinanceAddress = 801 [(wire_out) = true]; 126 MessageType_BinanceGetPublicKey = 802 [(wire_in) = true]; 127 MessageType_BinancePublicKey = 803 [(wire_out) = true]; 128 MessageType_BinanceSignTx = 804 [(wire_in) = true]; 129 MessageType_BinanceTxRequest = 805 [(wire_out) = true]; 130 MessageType_BinanceTransferMsg = 806 [(wire_in) = true]; 131 MessageType_BinanceOrderMsg = 807 [(wire_in) = true]; 132 MessageType_BinanceCancelMsg = 808 [(wire_in) = true]; 133 MessageType_BinanceSignedTx = 809 [(wire_out) = true]; 134 135 // Cosmos 136 MessageType_CosmosGetAddress = 900 [(wire_in) = true]; 137 MessageType_CosmosAddress = 901 [(wire_out) = true]; 138 MessageType_CosmosSignTx = 902 [(wire_in) = true]; 139 MessageType_CosmosMsgRequest = 903 [(wire_out) = true]; 140 MessageType_CosmosMsgAck = 904 [(wire_in) = true]; 141 MessageType_CosmosSignedTx = 905 [(wire_out) = true]; 142 143} 144 145//////////////////// 146// Basic messages // 147//////////////////// 148 149/** 150 * Request: Reset device to default state and ask for device details 151 * @next Features 152 */ 153message Initialize { 154} 155 156/** 157 * Request: Ask for device details (no device reset) 158 * @next Features 159 */ 160message GetFeatures { 161} 162 163/** 164 * Response: Reports various information about the device 165 * @prev Initialize 166 * @prev GetFeatures 167 */ 168message Features { 169 optional string vendor = 1; // name of the manufacturer, e.g. "bitcointrezor.com" 170 optional uint32 major_version = 2; // major version of the device, e.g. 1 171 optional uint32 minor_version = 3; // minor version of the device, e.g. 0 172 optional uint32 patch_version = 4; // patch version of the device, e.g. 0 173 optional bool bootloader_mode = 5; // is device in bootloader mode? 174 optional string device_id = 6; // device's unique identifier 175 optional bool pin_protection = 7; // is device protected by PIN? 176 optional bool passphrase_protection = 8; // is node/mnemonic encrypted using passphrase? 177 optional string language = 9; // device language 178 optional string label = 10; // device description label 179 repeated CoinType coins = 11; // supported coins (Deprecated. Use GetCoinTable instead) 180 optional bool initialized = 12; // does device contain seed? 181 optional bytes revision = 13; // SCM revision of firmware 182 optional bytes bootloader_hash = 14; // double sha256 hash of the bootloader 183 optional bool imported = 15; // was storage imported from an external source? 184 optional bool pin_cached = 16; // is PIN already cached in session? 185 optional bool passphrase_cached = 17; // is passphrase already cached in session? 186 repeated PolicyType policies = 18; // policies 187 optional string model = 21; // device hardware model 188 optional string firmware_variant = 22; // Firmware variant 189 optional bytes firmware_hash = 23; // double sha256 hash of the firmware 190 optional bool no_backup = 24; // Device was initialized without displaying recovery sentence. 191 optional bool wipe_code_protection = 25; 192} 193 194/** 195 * Request: Ask the device for its list of supported coins 196 * @next CoinTable 197 */ 198message GetCoinTable { 199 optional uint32 start = 1; 200 optional uint32 end = 2; 201} 202 203/** 204 * Response: A subset of the supported coins 205 * @prev GetCoinTable 206 */ 207message CoinTable { 208 repeated CoinType table = 1; 209 optional uint32 num_coins = 2; 210 optional uint32 chunk_size = 3; 211} 212 213/** 214 * Request: clear session (removes cached PIN, passphrase, etc). 215 * @next Success 216 */ 217message ClearSession { 218} 219 220/** 221 * Request: change language and/or label of the device 222 * @next Success 223 * @next Failure 224 * @next ButtonRequest 225 * @next PinMatrixRequest 226 */ 227message ApplySettings { 228 optional string language = 1; 229 optional string label = 2; 230 optional bool use_passphrase = 3; 231 optional uint32 auto_lock_delay_ms = 4; 232 optional uint32 u2f_counter = 5; 233} 234 235/** 236 * Request: Starts workflow for setting/changing/removing the PIN 237 * @next ButtonRequest 238 * @next PinMatrixRequest 239 */ 240message ChangePin { 241 optional bool remove = 1; // is PIN removal requested? 242} 243 244/** 245 * Request: Test if the device is alive, device sends back the message in Success response 246 * @next Success 247 */ 248message Ping { 249 optional string message = 1; // message to send back in Success message 250 optional bool button_protection = 2; // ask for button press 251 optional bool pin_protection = 3; // ask for PIN if set in device 252 optional bool passphrase_protection = 4; // ask for passphrase if set in device 253 optional bool wipe_code_protection = 5; // ask for wipe code if set in device 254} 255 256/** 257 * Response: Success of the previous request 258 */ 259message Success { 260 optional string message = 1; // human readable description of action or request-specific payload 261} 262 263/** 264 * Response: Failure of the previous request 265 */ 266message Failure { 267 optional FailureType code = 1; // computer-readable definition of the error state 268 optional string message = 2; // human-readable message of the error state 269} 270 271/** 272 * Response: Device is waiting for HW button press. 273 * @next ButtonAck 274 * @next Cancel 275 */ 276message ButtonRequest { 277 optional ButtonRequestType code = 1; 278 optional string data = 2; 279} 280 281/** 282 * Request: Computer agrees to wait for HW button press 283 * @prev ButtonRequest 284 */ 285message ButtonAck { 286} 287 288/** 289 * Response: Device is asking computer to show PIN matrix and awaits PIN encoded using this matrix scheme 290 * @next PinMatrixAck 291 * @next Cancel 292 */ 293message PinMatrixRequest { 294 optional PinMatrixRequestType type = 1; 295} 296 297/** 298 * Request: Computer responds with encoded PIN 299 * @prev PinMatrixRequest 300 */ 301message PinMatrixAck { 302 required string pin = 1; // matrix encoded PIN entered by user 303} 304 305/** 306 * Request: Abort last operation that required user interaction 307 * @prev ButtonRequest 308 * @prev PinMatrixRequest 309 * @prev PassphraseRequest 310 */ 311message Cancel { 312} 313 314/** 315 * Response: Device awaits encryption passphrase 316 * @next PassphraseAck 317 * @next Cancel 318 */ 319message PassphraseRequest { 320} 321 322/** 323 * Request: Send passphrase back 324 * @prev PassphraseRequest 325 */ 326message PassphraseAck { 327 required string passphrase = 1; 328} 329 330/** 331 * Request: Request a sample of random data generated by hardware RNG. May be used for testing. 332 * @next ButtonRequest 333 * @next Entropy 334 * @next Failure 335 */ 336message GetEntropy { 337 required uint32 size = 1; // size of requested entropy 338} 339 340/** 341 * Response: Reply with random data generated by internal RNG 342 * @prev GetEntropy 343 */ 344message Entropy { 345 required bytes entropy = 1; // stream of random generated bytes 346} 347 348/** 349 * Request: Ask device for public key corresponding to address_n path 350 * @next PassphraseRequest 351 * @next PublicKey 352 * @next Failure 353 */ 354message GetPublicKey { 355 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 356 optional string ecdsa_curve_name = 2; // ECDSA curve name to use 357 optional bool show_display = 3; // optionally show on display before sending the result 358 optional string coin_name = 4 [default='Bitcoin']; 359 optional InputScriptType script_type = 5 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.) 360} 361 362/** 363 * Response: Contains public key derived from device private seed 364 * @prev GetPublicKey 365 */ 366message PublicKey { 367 required HDNodeType node = 1; // BIP32 public node 368 optional string xpub = 2; // serialized form of public node 369} 370 371/** 372 * Request: Ask device for address corresponding to address_n path 373 * @next PassphraseRequest 374 * @next Address 375 * @next Failure 376 */ 377message GetAddress { 378 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 379 optional string coin_name = 2 [default='Bitcoin']; 380 optional bool show_display = 3 ; // optionally show on display before sending the result 381 optional MultisigRedeemScriptType multisig = 4; // filled if we are showing a multisig address 382 optional InputScriptType script_type = 5 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.) 383} 384 385/** 386 * Request: Ask device for Ethereum address corresponding to address_n path 387 * @next PassphraseRequest 388 * @next EthereumAddress 389 * @next Failure 390 */ 391message EthereumGetAddress { 392 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 393 optional bool show_display = 2; // optionally show on display before sending the result 394} 395 396/** 397 * Response: Contains address derived from device private seed 398 * @prev GetAddress 399 */ 400message Address { 401 required string address = 1; // Coin address in Base58 encoding 402} 403 404/** 405 * Response: Contains an Ethereum address derived from device private seed 406 * @prev EthereumGetAddress 407 */ 408message EthereumAddress { 409 required bytes address = 1; // Coin address as an Ethereum 160 bit hash 410 optional string address_str = 2; 411} 412 413/** 414 * Request: Request device to wipe all sensitive data and settings 415 * @next ButtonRequest 416 */ 417message WipeDevice { 418} 419 420/** 421 * Request: Load seed and related internal settings from the computer 422 * @next ButtonRequest 423 * @next Success 424 * @next Failure 425 */ 426message LoadDevice { 427 optional string mnemonic = 1; // seed encoded as BIP-39 mnemonic (12, 18 or 24 words) 428 optional HDNodeType node = 2; // BIP-32 node 429 optional string pin = 3; // set PIN protection 430 optional bool passphrase_protection = 4; // enable master node encryption using passphrase 431 optional string language = 5 [default='english']; // device language 432 optional string label = 6; // device label 433 optional bool skip_checksum = 7; // do not test mnemonic for valid BIP-39 checksum 434 optional uint32 u2f_counter = 8; // U2F Counter 435} 436 437/** 438 * Request: Ask device to do initialization involving user interaction 439 * @next EntropyRequest 440 * @next Failure 441 */ 442message ResetDevice { 443 optional bool display_random = 1; // display entropy generated by the device before asking for additional entropy 444 optional uint32 strength = 2 [default=256]; // strength of seed in bits 445 optional bool passphrase_protection = 3; // enable master node encryption using passphrase 446 optional bool pin_protection = 4; // enable PIN protection 447 optional string language = 5 [default='english']; // device language 448 optional string label = 6; // device label 449 optional bool no_backup = 7; // Initialize without ever showing the recovery sentence. 450 optional uint32 auto_lock_delay_ms = 8; // Screensaver Timeout 451 optional uint32 u2f_counter = 9; // U2F Counter 452} 453 454/** 455 * Response: Ask for additional entropy from host computer 456 * @prev ResetDevice 457 * @next EntropyAck 458 */ 459message EntropyRequest { 460} 461 462/** 463 * Request: Provide additional entropy for seed generation function 464 * @prev EntropyRequest 465 * @next ButtonRequest 466 */ 467message EntropyAck { 468 optional bytes entropy = 1; // 256 bits (32 bytes) of random data 469} 470 471/** 472 * Request: Start recovery workflow asking user for specific words of mnemonic 473 * Used to recovery device safely even on untrusted computer. 474 * @next WordRequest 475 */ 476message RecoveryDevice { 477 optional uint32 word_count = 1; // number of words in BIP-39 mnemonic 478 optional bool passphrase_protection = 2; // enable master node encryption using passphrase 479 optional bool pin_protection = 3; // enable PIN protection 480 optional string language = 4 [default='english']; // device language 481 optional string label = 5; // device label 482 optional bool enforce_wordlist = 6; // enforce BIP-39 wordlist during the process 483 optional bool use_character_cipher = 7; // an optional way to input recovery sentence by character using a cipher 484 optional uint32 auto_lock_delay_ms = 8; // Screensaver Timeout 485 optional uint32 u2f_counter = 9; // U2F Counter 486 optional bool dry_run = 10; // perform dry-run recovery workflow (for safe mnemonic validation) 487} 488 489/** 490 * Response: Device is waiting for user to enter word of the mnemonic 491 * Its position is shown only on device's internal display. 492 * @prev RecoveryDevice 493 * @prev WordAck 494 */ 495message WordRequest { 496} 497 498/** 499 * Request: Computer replies with word from the mnemonic 500 * @prev WordRequest 501 * @next WordRequest 502 * @next Success 503 * @next Failure 504 */ 505message WordAck { 506 required string word = 1; // one word of mnemonic on asked position 507} 508 509/** 510 * Response: Device is waiting for user to enter character of the mnemonic using cipher. 511 * The cipher is shown on device's internal display. 512 * @prev RecoveryDevice 513 * @prev CharacterAck 514 */ 515message CharacterRequest { 516 required uint32 word_pos = 1; // word position in BIP-39 mnemonic 517 required uint32 character_pos = 2; // character position 518} 519 520/** 521 * Request: Computer replies with character from the mnemonic using cipher 522 * @prev CharacterRequest 523 * @next CharacterRequest 524 * @next Failure 525 */ 526message CharacterAck { 527 optional string character = 1; // one character of mnemonic using cipher 528 optional bool delete = 2; // request to delete previous character from ciphered mnemonic 529 optional bool done = 3; // marks there are no more characters left for ciphered mnemonic 530} 531 532////////////////////////////// 533// Message signing messages // 534////////////////////////////// 535 536/** 537 * Request: Ask device to sign message 538 * @next MessageSignature 539 * @next Failure 540 */ 541message SignMessage { 542 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 543 required bytes message = 2; // message to be signed 544 optional string coin_name = 3 [default='Bitcoin']; // coin to use for signing 545 optional InputScriptType script_type = 4 [default=SPENDADDRESS]; // used to distinguish between various address formats (non-segwit, segwit, etc.) 546} 547 548/** 549 * Request: Ask device to verify message 550 * @next Success 551 * @next Failure 552 */ 553message VerifyMessage { 554 optional string address = 1; // address to verify 555 optional bytes signature = 2; // signature to verify 556 optional bytes message = 3; // message to verify 557 optional string coin_name = 4 [default='Bitcoin']; // coin to use for verifying 558} 559 560/** 561 * Response: Signed message 562 * @prev SignMessage 563 */ 564message MessageSignature { 565 optional string address = 1; // address used to sign the message 566 optional bytes signature = 2; // signature of the message 567} 568 569/////////////////////////// 570// Encryption/decryption // 571/////////////////////////// 572 573/** 574 * Request: Ask device to encrypt message 575 * @next EncryptedMessage 576 * @next Failure 577 */ 578message EncryptMessage { 579 optional bytes pubkey = 1; // public key 580 optional bytes message = 2; // message to encrypt 581 optional bool display_only = 3; // show just on display? (don't send back via wire) 582 repeated uint32 address_n = 4; // BIP-32 path to derive the signing key from master node 583 optional string coin_name = 5 [default='Bitcoin']; // coin to use for signing 584} 585 586/** 587 * Response: Encrypted message 588 * @prev EncryptMessage 589 */ 590message EncryptedMessage { 591 optional bytes nonce = 1; // nonce used during encryption 592 optional bytes message = 2; // encrypted message 593 optional bytes hmac = 3; // message hmac 594} 595 596/** 597 * Request: Ask device to decrypt message 598 * @next Success 599 * @next Failure 600 */ 601message DecryptMessage { 602 repeated uint32 address_n = 1; // BIP-32 path to derive the decryption key from master node 603 optional bytes nonce = 2; // nonce used during encryption 604 optional bytes message = 3; // message to decrypt 605 optional bytes hmac = 4; // message hmac 606} 607 608/** 609 * Response: Decrypted message 610 * @prev DecryptedMessage 611 */ 612message DecryptedMessage { 613 optional bytes message = 1; // decrypted message 614 optional string address = 2; // address used to sign the message (if used) 615} 616 617/** 618 * Request: Ask device to encrypt or decrypt value of given key 619 * @next CipheredKeyValue 620 * @next Failure 621 */ 622message CipherKeyValue { 623 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 624 optional string key = 2; // key component of key:value 625 optional bytes value = 3; // value component of key:value 626 optional bool encrypt = 4; // are we encrypting (True) or decrypting (False)? 627 optional bool ask_on_encrypt = 5; // should we ask on encrypt operation? 628 optional bool ask_on_decrypt = 6; // should we ask on decrypt operation? 629 optional bytes iv = 7; // initialization vector (will be computed if not set) 630} 631 632/** 633 * Response: Return ciphered/deciphered value 634 * @prev CipherKeyValue 635 */ 636message CipheredKeyValue { 637 optional bytes value = 1; // ciphered/deciphered value 638} 639 640////////////////////////////////// 641// Transaction signing messages // 642////////////////////////////////// 643 644/** 645 * Request: Ask device to sign transaction 646 * @next PassphraseRequest 647 * @next PinMatrixRequest 648 * @next TxRequest 649 * @next Failure 650 */ 651message SignTx { 652 required uint32 outputs_count = 1; // number of transaction outputs 653 required uint32 inputs_count = 2; // number of transaction inputs 654 optional string coin_name = 3 [default='Bitcoin']; // coin to use 655 optional uint32 version = 4 [default=1]; // transaction version 656 optional uint32 lock_time = 5 [default=0]; // transaction lock_time 657 optional uint32 expiry = 6; // only for Decred and Zcash 658 optional bool overwintered = 7; // only for Zcash 659 optional uint32 version_group_id = 8; // only for Zcash, nVersionGroupId when overwintered is set 660 optional uint32 branch_id = 10; // only for Zcash, BRANCH_ID when overwintered is set 661} 662 663/** 664 * Response: Device asks for information for signing transaction or returns the last result 665 * If request_index is set, device awaits TxAck message (with fields filled in according to request_type) 666 * If signature_index is set, 'signature' contains signed input of signature_index's input 667 * @prev SignTx 668 * @prev TxAck 669 */ 670message TxRequest { 671 optional RequestType request_type = 1; // what should be filled in TxAck message? 672 optional TxRequestDetailsType details = 2; // request for tx details 673 optional TxRequestSerializedType serialized = 3; // serialized data and request for next 674} 675 676/** 677 * Request: Reported transaction data 678 * @prev TxRequest 679 * @next TxRequest 680 */ 681message TxAck { 682 optional TransactionType tx = 1; 683} 684 685/** 686 * Request: Reported raw transaction data 687 * @prev TxRequest 688 * @next TxRequest 689 */ 690message RawTxAck { 691 optional RawTransactionType tx = 1; 692} 693 694/** 695 * Request: Ask device to sign transaction 696 * All fields are optional from the protocol's point of view. Each field defaults to value `0` if missing. 697 * Note: the first at most 1024 bytes of data MUST be transmitted as part of this message. 698 * @next PassphraseRequest 699 * @next PinMatrixRequest 700 * @next EthereumTxRequest 701 * @next Failure 702 */ 703message EthereumSignTx { 704 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 705 optional bytes nonce = 2; // <=256 bit unsigned big endian 706 optional bytes gas_price = 3; // <=256 bit unsigned big endian (in wei) 707 optional bytes gas_limit = 4; // <=256 bit unsigned big endian 708 optional bytes to = 5; // 160 bit address hash 709 optional bytes value = 6; // <=256 bit unsigned big endian (in wei) 710 optional bytes data_initial_chunk = 7; // The initial data chunk (<= 1024 bytes) 711 optional uint32 data_length = 8; // Length of transaction payload 712 repeated uint32 to_address_n = 9; // BIP-32 path to derive key for fund transfer 713 optional OutputAddressType address_type = 10; // output address type 714 optional ExchangeType exchange_type = 11; // exchange type data 715 optional uint32 chain_id = 12; // Chain Id for EIP 155 716 optional bytes token_value = 100; // How many tokens to send 717 optional bytes token_to = 101; // 160 bit address hash to send tokens to 718 optional string token_shortcut = 102; // 3 or 4 character token identifier 719 optional uint32 tx_type = 103; // (only for Wanchain) 720} 721 722/** 723 * Response: Device asks for more data from transaction payload, or returns the signature. 724 * If data_length is set, device awaits that many more bytes of payload. 725 * Otherwise, the signature_* fields contain the computed transaction signature. All three fields will be present. 726 * @prev EthereumSignTx 727 * @next EthereumTxAck 728 */ 729message EthereumTxRequest { 730 optional uint32 data_length = 1; // Number of bytes being requested (<= 1024) 731 optional uint32 signature_v = 2; // Computed signature (recovery parameter, limited to 27 or 28) 732 optional bytes signature_r = 3; // Computed signature R component (256 bit) 733 optional bytes signature_s = 4; // Computed signature S component (256 bit) 734 optional bytes hash = 5; // Computed hash using SHA3 (keccak_ctx) 735 optional bytes signature_der = 6; // Computed signature in DER format 736} 737 738/** 739 * Request: Transaction payload data. 740 * @prev EthereumTxRequest 741 * @next EthereumTxRequest 742 */ 743message EthereumTxAck { 744 optional bytes data_chunk = 1; // Bytes from transaction payload (<= 1024 bytes) 745} 746 747//////////////////////////////////////// 748// Ethereum: Message signing messages // 749//////////////////////////////////////// 750 751/** 752 * Request: Ask device to sign message 753 * @next EthereumMessageSignature 754 * @next Failure 755 */ 756message EthereumSignMessage { 757 repeated uint32 address_n = 1; // BIP-32 path to derive the key from master node 758 required bytes message = 2; // message to be signed 759} 760 761/** 762 * Request: Ask device to verify message 763 * @next Success 764 * @next Failure 765 */ 766message EthereumVerifyMessage { 767 optional bytes address = 1; // address to verify 768 optional bytes signature = 2; // signature to verify 769 optional bytes message = 3; // message to verify 770} 771 772/** 773 * Response: Signed message 774 * @prev EthereumSignMessage 775 */ 776message EthereumMessageSignature { 777 optional bytes address = 1; // address used to sign the message 778 optional bytes signature = 2; // signature of the message 779} 780 781/////////////////////// 782// Identity messages // 783/////////////////////// 784 785/** 786 * Request: Ask device to sign identity 787 * @next SignedIdentity 788 * @next Failure 789 */ 790message SignIdentity { 791 optional IdentityType identity = 1; // identity 792 optional bytes challenge_hidden = 2; // non-visible challenge 793 optional string challenge_visual = 3; // challenge shown on display (e.g. date+time) 794 optional string ecdsa_curve_name = 4; // ECDSA curve name to use 795} 796 797/** 798 * Response: Device provides signed identity 799 * @prev SignIdentity 800 */ 801message SignedIdentity { 802 optional string address = 1; // identity address 803 optional bytes public_key = 2; // identity public key 804 optional bytes signature = 3; // signature of the identity data 805} 806 807///////////////////// 808// Policy messages // 809///////////////////// 810 811/** 812 * Request: Ask device to apply policy 813 * @next Success 814 * @next Failure 815 * @next ButtonRequest 816 * @next PinMatrixRequest 817 */ 818message ApplyPolicies { 819 repeated PolicyType policy = 1; // policy 820} 821 822///////////////////////// 823// Bootloader Verification 824///////////////////////// 825 826/** 827 * Request: Ask the device to return a hash of flash memory 828 * @next FlashHashResponse 829 * @next Failure 830 */ 831message FlashHash { 832 optional uint32 address = 1; 833 optional uint32 length = 2; 834 optional bytes challenge = 3; 835} 836 837/** 838 * Request: Write a chunk of data into flash memory 839 * @next FlashHashResponse 840 * @next Failure 841 */ 842message FlashWrite { 843 optional uint32 address = 1; 844 optional bytes data = 2; 845 optional bool erase = 3; 846} 847 848/** 849 * Response: Returns hash of requested data sector 850 * @prev FlashHash 851 * @prev FlashWrite 852 */ 853 message FlashHashResponse { 854 optional bytes data = 1; 855 } 856 857/** 858 * Request: Returns a portion of flash requested 859 * @next DebugLinkFlashDumpResponse 860 * @next Failure 861 */ 862message DebugLinkFlashDump { 863 optional uint32 address = 1; 864 optional uint32 length = 2; 865} 866 867/** 868 * Response: flash data 869 * @prev DebugLinkFlashDump 870 */ 871message DebugLinkFlashDumpResponse { 872 optional bytes data = 1; 873} 874 875/** 876 * Request: Ask the device to perform a soft reset 877 */ 878message SoftReset { 879} 880 881///////////////////////// 882// Bootloader messages // 883///////////////////////// 884 885/** 886 * Request: Ask device to erase its firmware 887 * @next Success 888 * @next Failure 889 */ 890message FirmwareErase { 891} 892 893/** 894 * Request: Send firmware in binary form to the device 895 * @next Success 896 * @next Failure 897 */ 898message FirmwareUpload { 899 required bytes payload_hash = 1; // sha256 hash of payload (meta + firmware) 900 required bytes payload = 2; // firmware to be loaded into device 901} 902 903///////////////////////////////////////////////////////////// 904// Debug messages (only available if DebugLink is enabled) // 905///////////////////////////////////////////////////////////// 906 907/** 908 * Request: "Press" the button on the device 909 * @next Success 910 */ 911message DebugLinkDecision { 912 required bool yes_no = 1; // true for "Confirm", false for "Cancel" 913} 914 915/** 916 * Request: Computer asks for device state 917 * @next DebugLinkState 918 */ 919message DebugLinkGetState { 920} 921 922/** 923 * Response: Device current state 924 * @prev DebugLinkGetState 925 */ 926message DebugLinkState { 927 optional bytes layout = 1; // raw buffer of display 928 optional string pin = 2; // current PIN, blank if PIN is not set/enabled 929 optional string matrix = 3; // current PIN matrix 930 optional string mnemonic = 4; // current BIP-39 mnemonic 931 optional HDNodeType node = 5; // current BIP-32 node 932 optional bool passphrase_protection = 6; // is node/mnemonic encrypted using passphrase? 933 optional string reset_word = 7; // word on device display during ResetDevice workflow 934 optional bytes reset_entropy = 8; // current entropy during ResetDevice workflow 935 optional string recovery_fake_word = 9; // (fake) word on display during RecoveryDevice workflow 936 optional uint32 recovery_word_pos = 10; // index of mnemonic word the device is expecting during RecoveryDevice workflow 937 optional string recovery_cipher = 11; // current recovery cipher 938 optional string recovery_auto_completed_word = 12; // last auto completed recovery word 939 optional bytes firmware_hash = 13; // hash of the application and meta header 940 optional bytes storage_hash = 14; // hash of storage 941} 942 943/** 944 * Request: Ask device to restart 945 */ 946message DebugLinkStop { 947} 948 949/** 950 * Response: Device wants host to log event 951 */ 952message DebugLinkLog { 953 optional uint32 level = 1; 954 optional string bucket = 2; 955 optional string text = 3; 956} 957 958/** 959 * Request: Ask device to fill config area with sample data (used for testing firmware upload) 960 */ 961message DebugLinkFillConfig { 962} 963 964/** 965 * Request: Starts workflow for setting/removing the wipe code 966 * @start 967 * @next Success 968 * @next Failure 969 */ 970 message ChangeWipeCode { 971 optional bool remove = 1; // is wipe code removal requested? 972} 973