Specs
Status Keycard Usage
A
Aaryamann Challani
and
J
on Aug 05, 2024
Edit on GitHub

  • Account: A valid BIP-32 compliant key.
  • Multiaccount: An account from which multiple Accounts can be derived.

This specification describes how an application can use the Status Keycard to -

  1. 1
    Create Multiaccounts
  2. 2
    Store Multiaccounts
  3. 3
    Use Multiaccounts for transaction or message signing
  4. 4
    Derive Accounts from Multiaccounts

More documentation on the Status Keycard can be found here

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.

To initialize the keycard for use with the application. The keycard is locked with a 6 digit pin.

{
  "pin": 6_digit_pin
}
{
  "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.

To fetch if the keycard is ready to be used by the application.

The requester MAY add a pairing field to filter through the generated keys

{
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt> OR null
}
{
  "initialized?": false
}
{
  "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
}

To establish a secure communication channel described here, the keycard and the client device need to be paired.

{
  "password": password_to_unlock_keycard
}
"<shared_secret>/<pairing_index>/<256_bit_salt>"

To generate a new set of keys and load them onto the keycard.

{
  "mnemonic": 12_word_mnemonic,
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
  "pin": 6_digit_pin
}
{
  "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,
}

To fetch the keys that are currently loaded on the keycard.

{
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
  "pin": 6_digit_pin
}
{
  "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,
}

To sign a transaction using the keycard, passing in the pairing information and the transaction to be signed.

{
  "hash": 64_byte_hash_of_the_transaction,
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
  "pin": 6_digit_pin,
  "path": bip32_path_to_the_key
}
<256_bit_signature>

To export a key from the keycard, passing in the pairing information and the path to the key to be exported.

{
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
  "pin": 6_digit_pin,
  "path": bip32_path_to_the_key
}
<256_bit_public_key>

To verify the pin of the keycard.

{
  "pin": 6_digit_pin
}
1_digit_status_code

Status code reference:

  • 3: PIN is valid

To change the pin of the keycard.

{
  "new-pin": 6_digit_new_pin,
  "current-pin": 6_digit_new_pin,
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>
}
true
false

If the Keycard is blocked due to too many incorrect pin attempts, it can be unblocked using the PUK.

{
  "puk": 12_digit_recovery_code,
  "new-pin": 6_digit_new_pin,
  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>
}
true
false

Any application that uses the Status Keycard MAY implement the following flows according to the actions listed above.

  1. 1
    The user initializes the Keycard using the /init-keycard endpoint.
  2. 2
    The user pairs the Keycard with the client device using the /pair endpoint.
  3. 3
    The user generates a new set of keys using the /generate-and-load-keys endpoint.
  4. 4
    The user can now use the Keycard to sign transactions using the /sign endpoint.

  1. 1
    The user pairs the Keycard with the client device using the /pair endpoint.
  2. 2
    The user can now use the Keycard to sign transactions using the /sign endpoint.

  1. 1
    The user pairs the Keycard with the new client device using the /pair endpoint.
  2. 2
    The user can now use the Keycard to sign transactions using the /sign endpoint.

  1. 1
    The user verifies the pin of the Keycard using the /verify-pin endpoint.

  1. 1
    The user changes the pin of the Keycard using the /change-pin endpoint.

  1. 1
    The user unblocks the Keycard using the /unblock-pin endpoint.

Inherits the security considerations of Status Keycard

Inherits the privacy considerations of Status Keycard

Copyright and related rights waived via CC0.

  1. 1
  2. 2
  3. 3