--- title: 63/STATUS-Keycard-Usage name: Status Keycard Usage status: draft category: Standards Track description: Describes how an application can use the Status Keycard to create, store and transact with different account addresses. editor: Aaryamann Challani \ contributors: - Jimmy Debe \ sidebar_position: 63 --- ## Terminology - **Account**: A valid [BIP-32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) compliant key. - **Multiaccount**: An account from which multiple Accounts can be derived. ## Abstract This specification describes how an application can use the Status Keycard to - 1. Create Multiaccounts 2. Store Multiaccounts 3. Use Multiaccounts for transaction or message signing 4. Derive Accounts from Multiaccounts More documentation on the Status Keycard can be found [here](https://keycard.tech/docs/) ## Motivation The Status Keycard is a hardware wallet that can be used to store and sign transactions. For the purpose of the Status App, this specification describes how the Keycard SHOULD be used to store and sign transactions. ## Usage ### Endpoints #### 1. Initialize Keycard (`/init-keycard`) To initialize the keycard for use with the application. The keycard is locked with a 6 digit pin. #### Request wire format ```json { "pin": 6_digit_pin } ``` #### Response wire format ```json { "password": password_to_unlock_keycard, "puk": 12_digit_recovery_code, "pin": provided_pin, } ``` The keycard MUST be initialized before it can be used with the application. The application SHOULD provide a way to recover the keycard in case the pin is forgotten. ### 2. Get Application Info (`/get-application-info`) To fetch if the keycard is ready to be used by the application. #### Request wire format The requester MAY add a `pairing` field to filter through the generated keys ```json { "pairing": \/\/\<256_bit_salt\> OR null } ``` #### Response wire format ##### If the keycard is not initialized yet ```json { "initialized?": false } ``` ##### If the keycard is initialized ```json { "free-pairing-slots": number, "app-version": major_version.minor_version, "secure-channel-pub-key": valid_bip32_key,, "key-uid": unique_id_of_the_default_key, "instance-uid": unique_instance_id, "paired?": bool, "has-master-key?": bool, "initialized?" true } ``` ### 3. Pairing the Keycard to the Client device (`/pair`) To establish a secure communication channel described [here](https://keycard.tech/docs/apdu/opensecurechannel.html), the keycard and the client device need to be paired. #### Request wire format ```json { "password": password_to_unlock_keycard } ``` #### Response wire format ```json "\/\/\<256_bit_salt\>" ``` ### 4. Generate a new set of keys (`/generate-and-load-keys`) To generate a new set of keys and load them onto the keycard. #### Request wire format ```json { "mnemonic": 12_word_mnemonic, "pairing": \/\/\<256_bit_salt\>, "pin": 6_digit_pin } ``` #### Response wire format ```json { "whisper-address": 20_byte_whisper_compatible_address, "whisper-private-key": whisper_private_key, "wallet-root-public-key": 256_bit_wallet_root_public_key, "encryption-public-key": 256_bit_encryption_public_key,, "wallet-root-address": 20_byte_wallet_root_address, "whisper-public-key": 256_bit_whisper_public_key, "address": 20_byte_address, "wallet-address": 20_byte_wallet_address,, "key-uid": 64_byte_unique_key_id, "wallet-public-key": 256_bit_wallet_public_key, "public-key": 256_bit_public_key, "instance-uid": 32_byte_unique_instance_id, } ``` ### 5. Get a set of generated keys (`/get-keys`) To fetch the keys that are currently loaded on the keycard. #### Request wire format ```json { "pairing": \/\/\<256_bit_salt\>, "pin": 6_digit_pin } ``` #### Response wire format ```json { "whisper-address": 20_byte_whisper_compatible_address, "whisper-private-key": whisper_private_key, "wallet-root-public-key": 256_bit_wallet_root_public_key, "encryption-public-key": 256_bit_encryption_public_key, "wallet-root-address": 20_byte_wallet_root_address, "whisper-public-key": 256_bit_whisper_public_key, "address": 20_byte_address, "wallet-address": 20_byte_wallet_address, "key-uid": 64_byte_unique_key_id, "wallet-public-key": 256_bit_wallet_public_key, "public-key": 256_bit_public_key, "instance-uid": 32_byte_unique_instance_id, } ``` ### 6. Sign a transaction (`/sign`) To sign a transaction using the keycard, passing in the pairing information and the transaction to be signed. #### Request wire format ```json { "hash": 64_byte_hash_of_the_transaction, "pairing": \/\/\<256_bit_salt\>, "pin": 6_digit_pin, "path": bip32_path_to_the_key } ``` #### Response wire format ```json \<256_bit_signature\> ``` ### 7. Export a key (`/export-key`) To export a key from the keycard, passing in the pairing information and the path to the key to be exported. #### Request wire format ```json { "pairing": \/\/\<256_bit_salt\>, "pin": 6_digit_pin, "path": bip32_path_to_the_key } ``` #### Response wire format ```json \<256_bit_public_key\> ``` ### 8. Verify a pin (`/verify-pin`) To verify the pin of the keycard. #### Request wire format ```json { "pin": 6_digit_pin } ``` #### Response wire format ```json 1_digit_status_code ``` Status code reference: - 3: PIN is valid \