95 lines
6.3 KiB
Markdown
95 lines
6.3 KiB
Markdown
|
# Status Wallet UX guidelines
|
||
|
|
|
||
|
|
The scope of this document is to describe the interactions between the hardware wallet, the user and client applications.
|
||
|
|
Technical details about the commands mentioned here are to be found in the [APPLICATION.MD](APPLICATION.MD) file.
|
||
|
|
|
||
|
|
## Physical interaction
|
||
|
|
|
||
|
|
The applet is installed on a regular Smart Card (plastic card) with contacted and/or contactless interface. Since the
|
||
|
|
card does not have any user input or output devices, all input and output happens through the host device. The host
|
||
|
|
device needs a card reader to interface with the card.
|
||
|
|
|
||
|
|
Each card will have a uniquely generated 12-digits PUK code (used to unblock the PIN) and a unique pairing code. The
|
||
|
|
format of the pairing code must be decided, it can be anything since in the end it will be converted to a 256-bit secret.
|
||
|
|
These codes cannot be changed.
|
||
|
|
|
||
|
|
The initial PIN of the card is "000000" and can be changed by the user. The length is always 6 digits. The user has 3
|
||
|
|
attempts to insert the correct PIN, after which it is blocked. The PIN can be reset by using the PUK. The user has 5
|
||
|
|
attempts to insert the correct PUK.
|
||
|
|
|
||
|
|
## Application selection
|
||
|
|
|
||
|
|
When the client detects a SmartCard, it should try to select the Status Wallet application by sending a selection command.
|
||
|
|
The applet will respond providing details useful for the next steps.
|
||
|
|
|
||
|
|
## PIN sessions
|
||
|
|
|
||
|
|
Many operations require the PIN to be authenticated. PIN entry scheme is the same as the one used for SIM-cards and follows
|
||
|
|
the rules described above. Once a PIN is authenticated, it remains authenticated until the card is reset, loses powers or
|
||
|
|
the application is re-selected. Since the card does not have a clock, if the client wants to reset PIN verification status
|
||
|
|
after a specific time/inactivity interval, it should keep track of the time itself and reset the session as described above.
|
||
|
|
|
||
|
|
## Pairing
|
||
|
|
|
||
|
|
A card can pair with up to 5 devices. The number of remaining pairing slot is given as a response to application selection.
|
||
|
|
The client will also receive an identifier, so it can recognize if it already paired with this card. Pairing must only
|
||
|
|
be done once and requires user interaction in form of pairing code entry. Keeping the generated pairing key secret is
|
||
|
|
critical to guarantee secure communication between card and client. However pairing alone does not give any access to the
|
||
|
|
keys stored on card or any other sensitive functionality, so the pairing code itself is not as sensitive.
|
||
|
|
|
||
|
|
## Unpairing
|
||
|
|
|
||
|
|
Unpairing allows to recover a pairing slot. An authenticated device can unpair itself or any other paired device. This
|
||
|
|
step requires PIN authorization. Since the card does not provide a list of paired devices, from a UI perspective the only
|
||
|
|
two options that make sense are "Unpair this device" and "Unpair all others".
|
||
|
|
|
||
|
|
## Initialization
|
||
|
|
|
||
|
|
When the card is delivered, it does not contain any key so it is not able to operate properly. The PIN is set to a default
|
||
|
|
one as well and must be changed. The GET STATUS command can be used to determine if the card is ready to be used or not.
|
||
|
|
|
||
|
|
The card is able to generate the mnemonic phrase internally and send it to the client as a sequence of 16-bit numbers which
|
||
|
|
are the indexes in the word dictionary. The actual key generation must happen off-card however, because the applet does not
|
||
|
|
implement PBKDF-2 to convert the phrase in a BIP-39 binary seed. The applet supports loading either the full master keypair
|
||
|
|
(private and public) or the binary seed. However the second option only works if the card supports public key derivation and
|
||
|
|
these are hard to get, since this function has been added to the JavaCard standard only in revision 3.0.5. It is critical
|
||
|
|
that the client destroys all copies of the key immediately after loading them to the card by explicitly clearing the memory
|
||
|
|
areas used to store them.
|
||
|
|
|
||
|
|
Initialization requires the PIN to be authenticated so it would be better if, upon detecting a new card, the client would
|
||
|
|
first prompt to change PIN (a step which includes PIN verification) and only after this step generates key.
|
||
|
|
|
||
|
|
The process of generating and loading new keys can also be repeated on an already initialized card. This step does not
|
||
|
|
reset the PIN to factory condition but permanently destroys the currently stored keys, so a fat huge warning must be
|
||
|
|
issued.
|
||
|
|
|
||
|
|
As with all HD-wallets, the client should show the mnemonic phrase to the user and prompt them to write down the words.
|
||
|
|
This will allow recovering the keys in case the card is lost, permanently blocked or re-initialized. Although the mnemonic
|
||
|
|
phrase could be generated by the client itself, it is safer to use the card facilities since their RNG is certified.
|
||
|
|
|
||
|
|
## Signing transactions
|
||
|
|
|
||
|
|
The main function of the card is indeed signing transactions (thus authorizing them). Signing requires the PIN to be
|
||
|
|
authenticated (except in a case mentioned below). All transaction details will be shown on the client, because of the
|
||
|
|
physical limitations of the card. The card support BIP32 HD wallets, but the key derivation (used to navigate the wallet
|
||
|
|
hierarchy) and sign steps are separate from each other. The key derivation step also requires PIN authentication
|
||
|
|
(except in a case mentioned below) but since both steps are likely to happen in the same session, this only needs to be
|
||
|
|
done once. The user does not need to interact in this key derivation step, but depending on the depth of the selected
|
||
|
|
wallet it might take a while (up to 2 seconds). Signing itself can also take a while, so it is a good idea to show a waiting
|
||
|
|
indicator during this step.
|
||
|
|
|
||
|
|
The card signs the hash of the transaction provided by client, so it can actually be used to sign any 256-bit value, making
|
||
|
|
it flexible to eventually use it contexts other than Ethereum transactions.
|
||
|
|
|
||
|
|
The card also support defining a wallet path which is PIN-less. This path can be changed but can only be one at a given time
|
||
|
|
and cannot be the master wallet. Transactions using this wallet will not require PIN entry. Setting a PIN-less path requires
|
||
|
|
PIN authorization, but the setting is retained across sessions.
|
||
|
|
|
||
|
|
The GET STATUS command can be used to query the currently selected wallet. This allows skipping the key derivation step
|
||
|
|
if the needed wallet is selected already. The selected wallet is also retained across sessions.
|
||
|
|
|
||
|
|
## Exporting keys
|
||
|
|
|
||
|
|
Exporting the private key is not allowed, except if the selected wallet is m/1/1 (Whisper key). This step requires PIN
|
||
|
|
authorization.
|