status-im
/
status-keycard
mirror of https://github.com/status-im/status-keycard.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

remove outdate info, closes #25

This commit is contained in:
Michele Balistreri 2018-11-14 15:28:41 +03:00
parent 2ebb131d8e
commit 8f811a47f4
2 changed files with 28 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
CLIENT_NOTES.md
View File

@ -38,7 +38,8 @@ generation on establishment of a Secure Channel. The client must permanently sto
the secret generated during pairing and the index which the card assigned to this client. Said index must be provided the secret generated during pairing and the index which the card assigned to this client. Said index must be provided
when opening a Secure Channel so that the card knows with which client it is speaking. Since the pairing secret is when opening a Secure Channel so that the card knows with which client it is speaking. Since the pairing secret is
sensitive data, it should be stored as securely as possible, eventually with password protection. Losing this secret sensitive data, it should be stored as securely as possible, eventually with password protection. Losing this secret
allows an attacker to pose either as the client to the card or as the card to the client. allows an attacker to pose either as the client to the card or as the card to the client. It does not allow however
decrypting older communication and perform passive attacks.
Note that the card can only pair with a limited number of clients (currently 5). Unpairing allows to replace old clients Note that the card can only pair with a limited number of clients (currently 5). Unpairing allows to replace old clients
with new ones. with new ones.
@ -73,8 +74,8 @@ session.
## Wallet features and workflow ## Wallet features and workflow
Now that the client can finally talk with the applet and provide user authentication facilities, it is time to look on Now that the client can finally talk with the applet and provide user authentication facilities, it is time to look on
how to actually use the wallet. The wallet applet allows management of a single HD wallet as described in the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) how to actually use the wallet. The wallet applet allows management of a single HD wallet as described in the
specifications. It provides the following features [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) specifications. It provides the following features
1. Source of entropy to generate master seeds (GENERATE MNEMONIC). No PIN required (has no effect on card state). 1. Source of entropy to generate master seeds (GENERATE MNEMONIC). No PIN required (has no effect on card state).
2. Loading of master key (LOAD KEY). PIN required. The same command can be used to replace the loaded master key. 2. Loading of master key (LOAD KEY). PIN required. The same command can be used to replace the loaded master key.
@ -84,8 +85,7 @@ specifications. It provides the following features
transaction is signed and must be generate off-card. The actual transaction data are not sent to the card. transaction is signed and must be generate off-card. The actual transaction data are not sent to the card.
5. Setting/Unsetting a PIN-less path (SET PINLESS PATH). PIN required. It allows disabling PIN authentication for a 5. Setting/Unsetting a PIN-less path (SET PINLESS PATH). PIN required. It allows disabling PIN authentication for a
specific key path. specific key path.
6. Exporting keys (EXPORT KEY). PIN required. Currently this is only allowed if the current key path is that of the 6. Exporting keys (EXPORT KEY). PIN required. Exporting the private key is only allowed for specific keys.
Whisper key (m/1/1)
Additionally the GET STATUS command (no PIN required) allows retrieving information about the card status and the Additionally the GET STATUS command (no PIN required) allows retrieving information about the card status and the
current key path. current key path.
@ -116,9 +116,9 @@ that setting the PIN-less key path does not automatically set the current key pa
to use DERIVE KEY to get there. Only when the current key path matches the PIN-less one the SIGN command will not require to use DERIVE KEY to get there. Only when the current key path matches the PIN-less one the SIGN command will not require
PIN authentication. The master key can never be used without PIN. PIN authentication. The master key can never be used without PIN.
Finally, some keys can be exported (after PIN authentication). At the moment only the Whisper key (m/1/1) can be Finally, some keys can be exported (after PIN authentication). The public key can be exported for any key, while the
exported. The EXPORT KEY command does not automatically do key derivation. This means that you must use DERIVE KEY first private one only for specific keys. The EXPORT KEY command does not automatically do key derivation. This means that you
so that the current key path matches m/1/1 and only then will the EXPORT KEY command work. must use DERIVE KEY before exporting the desired key.
## Additional notes ## Additional notes
@ -127,18 +127,14 @@ so that the current key path matches m/1/1 and only then will the EXPORT KEY com
Keccak-256 (which is not available) making it useless. This mode of operation has been implemented before the current Keccak-256 (which is not available) making it useless. This mode of operation has been implemented before the current
one with precomputed hashes. It remains because if we get hold of a hardware platform implementing Keccak-256, or we one with precomputed hashes. It remains because if we get hold of a hardware platform implementing Keccak-256, or we
decide to implement it in software, we might want to operate this way. decide to implement it in software, we might want to operate this way.
2. The DERIVE KEY command on the current hardware platform can only be used in "assisted key derivation" mode, because 2. Communication has less overhead when using the T=1 protocol. However the card/reader/os combination I have seems to
it does not have support of the KeyAgreement.ALG_EC_SVDP_DH_PLAIN_XY algorithm. Assisted key derivation is indeed a
workaround which should be removed if we find a suitable hardware platform (currently there is no JavaCard 3.0.5
implementation that can be easily found on the low-volumes market)
3. Communication has less overhead when using the T=1 protocol. However the card/reader/os combination I have seems to
only work with T=0 (although all claim to support T=1). Contactless readers always emulate T=1 when operated through only work with T=0 (although all claim to support T=1). Contactless readers always emulate T=1 when operated through
the PC/SC interface. the PC/SC interface.
4. You can refer to the tests for examples of communication with the card. The manual-only signTransactionTest test in 3. You can refer to the tests for examples of communication with the card. The manual-only signTransactionTest test in
particular generates a real transaction, signs it and submits it to the network. particular generates a real transaction, signs it and submits it to the network.
5. If you test your client against our fork of jCardSim instead of a real card, keep in mind that it supports unassisted 4. If you test your client against our fork of jCardSim instead of a real card, keep in mind that it supports unassisted
key derivation, but you shouldn't use it because, as explained above, it wouldn't work on the card. key derivation, but you shouldn't use it because, as explained above, it wouldn't work on the card.
6. If using jCardSim, only use our fork, since some of the needed algorithms are unsupported in the upstream version. 5. If using jCardSim, only use our fork, since some of the needed algorithms are unsupported in the upstream version.
7. The pairing code is a randomly generated password (using whatever password generation algorithm is desired). This 6. The pairing code is a randomly generated password (using whatever password generation algorithm is desired). This
password must be converted to a 256-bit key using PBKDF2 with the salt "Status Hardware Wallet Lite" and 50000 iterations. password must be converted to a 256-bit key using PBKDF2 with the salt "Status Hardware Wallet Lite" and 50000 iterations.

24
UX_NOTES.md
View File

@ -10,12 +10,13 @@ card does not have any user input or output devices, all input and output happen
device needs a card reader to interface with the card. 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 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. pairing code is a password which must be converted to a 256-bit secret as defined in [CLIENT_NOTES.md](CLIENT_NOTES.md).
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 The initial PIN of the card can be set to "000000" or can be chosen by the user. The length is always 6 digits. The user
attempts to insert the correct PIN, after which it is blocked. The PIN can be reset by using the PUK. The user has 5 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
attempts to insert the correct PUK. 5 attempts to insert the correct PUK.
PIN, PUK and pairing password can be changed at any time by the user, after authenticating with the current PIN.
## Application selection ## Application selection
@ -45,8 +46,13 @@ two options that make sense are "Unpair this device" and "Unpair all others".
## Initialization ## 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 When the card is delivered, it does not contain any secret so it is not able to operate properly. In this state only the
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. INIT command will work, which allows setting the initial PIN, PUK and pairing password using a temporary secure channel.
After this first initialization, a master key must be stored on the card. It can be recovered from a mnemonic phrase,
generated ex-novo using BIP39 or internally on the card.
The GET STATUS command can be used to determine if the card is ready to be used for signing 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 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 are the indexes in the word dictionary. The actual key generation must happen off-card however, because the applet does not
@ -90,5 +96,5 @@ if the needed wallet is selected already. The selected wallet is also retained a
## Exporting keys ## Exporting keys
Exporting the private key is not allowed, except if the selected wallet is m/1/1 (Whisper key). This step requires PIN Exporting the private key is not allowed, except for specific key paths. This step requires PIN authorization. Public
authorization. keys can be exported for any path.