status-im/status-keycard
2
0
Fork 0
mirror of https://github.com/status-im/status-keycard.git synced 2025-01-16 16:54:12 +00:00
Code Issues Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
Michele Balistreri 2018-10-10 10:39:51 +02:00
parent c4365c1cef
commit 796449023d
2 changed files with 38 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
APPLICATION.MD
View File

@ -11,18 +11,22 @@ authentication.
Before any application command is processed, a Secure Channel session must be established as specified in the
[SECURE_CHANNEL.MD](SECURE_CHANNEL.MD) document.
## INITIALIZATION
After installation, the applet is not ready to operate and is in a pre-initializaed state. In this state the applet can
only process the SELECT and INIT command. The INIT command is used to personalize the PIN, PUK and pairing secret, which
must be generated off-card.
## PIN
During installation the user's PIN is set to 000000 (six times zero). The PIN length is fixed at 6 digits. After 3
failed authentication attempts the PIN is blocked and authentication is not possible anymore. A blocked PIN can be
replaced and unblocked using a PUK. The PUK is a 12-digit number, unique for each installation and is generated off-card
and passed as an installation parameter to the applet according to the JavaCard specifications. After 5 failed attempts
to unblock the applet using the PUK, the PUK is blocked, meaning the wallet is lost.
The PIN length is fixed at 6 digits. After 3 failed authentication attempts the PIN is blocked and authentication is not
possible anymore. A blocked PIN can be replaced and unblocked using a PUK. The PUK is a 12-digit number. After 5 failed
attempts to unblock the applet using the PUK, the PUK is blocked, meaning the wallet is lost.
After authentication, the user remains authenticated until the application is either deselected or the card is reset.
Authentication with PIN is a requirement for most commands to succeed.
The PIN can be changed by the user after authentication.
The PIN and PUK can be changed by the user after authentication.
## Keys & Signature
@ -48,7 +52,7 @@ SW 0x6985 is returned. All tagged data structures are encoded in the [BER-TLV fo
* P1 = 0x04
* P2 = 0x00
* Data = 53746174757357616C6C6574417070 (hex)
* Response = Application Info Template
* Response = Application Info Template or ECC public key.
Response Data format:
- Tag 0xA4 = Application Info Template
@ -67,6 +71,26 @@ application, formatted on two bytes. The first byte is the major version and the
The Key UID can be either empty (when no key is loaded on card) or the SHA-256 hash of the master public key.
When the applet is in pre-initializated state, it only returns the ECC public key, BER-TLV encoded with tag 0x80.
### INIT
* CLA = 0x80
* INS = 0xFE
* P1 = 0x00
* P2 = 0x00
* Data = EC public key (LV encoded) | IV | encrypted payload
* Response SW = 0x9000 on success, 0x6D00 if the applet is already initialized
This command is only available when the applet is in pre-initialized state and successful execution brings the applet in
the initialized state. This command is needed to allow securely storing secrets on the applet at a different moment and
place than installation is taking place. Currently these are the PIN, PUK and pairing password.
The client must take the public key received after the SELECT command, generate a random keypair and perform EC-DH to
generate an AES key. It must then generate a random IV and encrypt the payload using AES-CBC with ISO/IEC 9797-1 Method
2 padding.
They payload is the concatenation of the PIN (6 digits/bytes), PUK (12 digits/bytes) and pairing secret (32 bytes).
### OPEN SECURE CHANNEL
The OPEN SECURE CHANNEL command is as specified in the [SECURE_CHANNEL.MD](SECURE_CHANNEL.MD).

12
SECURE_CHANNEL.MD
View File

@ -9,11 +9,13 @@ authentication for each APDU.
A short description of establishing a session is as follows
1. The client selects the application on card. The application responds with a public EC key.
2. The client sends an OPEN SECURE CHANNEL command with its public key. The EC-DH algorithm is used by both parties to
generate a shared 256-bit secret (more details below).
3. The generated secret is used as an AES key to encrypt all further communication. CBC mode is used with a random IV
generated for each APDU and prepended to the APDU payload. Both command and responses are encrypted.
4. The client sends a MUTUALLY AUTHENTICATE command to verify that the keys are matching and thus the secure channel is
2. The client sends an OPEN SECURE CHANNEL command with its public key and pairing index. The EC-DH algorithm is used by
both parties to generate a shared 256-bit secret (more details below).
3. The generated secret is concatenated with the pairing key and random data and hashed with SHA-512.
4. The first half of the generated value is used as an AES key to encrypt all further communication. CBC mode is used
with a random IV generated for each APDU and prepended to the APDU payload. The second half is used to MAC generation
and verification. Both command and responses are encrypted.
5. The client sends a MUTUALLY AUTHENTICATE command to verify that the keys are matching and thus the secure channel is
successfully established.
The EC keyset used by the card for the EC-DH algorithm is generated on-card on applet installation and is not used