2017-09-22 09:14:15 +00:00
# Status Wallet Application
## Overview
This application allows signing of transactions using ECDSA with a keyset stored on card. The keys are defined on the
SECP256k1 curve. Signing is available only after PIN authentication.
The keyset used for signing is generated externally and loaded on card. This is also only available after PIN
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.
## 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 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 all further commands to succeed.
The PIN can be changed by the user after authentication.
## Keys & Signature
The application allows loading a replacing of a single EC keyset, defined on the SECP256k1 curve. This keyset is used
to sign transactions. When the applet is first installed, no keyset is available so signing will fail. It is necessary
to first load the keyset in order for the application to be fully operational.
Signing of transactions is done by uploading the data in blocks no larger than 255 bytes (including the overhead caused
2017-09-25 07:53:20 +00:00
by the Secure Channel). Segmentation must be handled at the application protocol.
2017-09-22 09:14:15 +00:00
2017-10-09 12:06:59 +00:00
## APDUs
2017-09-22 09:14:15 +00:00
These are the commands supported by the application. When a command has a precondition clause and these are not met the
2017-10-09 12:06:59 +00:00
SW 0x6985 is returned. All tagged data structures are encoded in the [BER-TLV format](http://www.cardwerk.com/smartcards/smartcard_standard_ISO7816-4_annex-d.aspx)
2017-09-22 09:14:15 +00:00
### SELECT
* CLA = 0x00
* INS = 0xA4
* P1 = 0x04
* P2 = 0x00
* Data = 53746174757357616C6C6574417070 (hex)
* Response = The public key used to establish the SecureChannel
The SELECT command is documented in the ISO 7816-4 specifications and is used to select the application on the card,
making it the active one. The data field is the AID of the application. The response is the public key which must
be used by the client to establish the Secure Channel.
### OPEN SECURE CHANNEL
The OPEN SECURE CHANNEL command is as specified in the [SECURE_CHANNEL.MD](SECURE_CHANNEL.MD).
2017-10-09 14:12:21 +00:00
### GET STATUS
* CLA = 0x80
* INS = 0xF2
* P1 = 0x00
* P2 = 0x00
* Response SW = 0x9000 on success
* Response Data = Application Status Template
* Preconditions: Secure Channel must be opened
Response Data format:
- Tag 0xA3 = Application Status Template
- Tag 0xC0 = PIN retry count (1 byte)
- Tag 0xC1 = PUK retry count (1 byte)
- Tag 0xC2 = 0 if key is not initialized, 1 otherwise
- Tag 0xC3 = 0 if public key derivation is not supported, 1 otherwise
2017-09-22 09:14:15 +00:00
### VERIFY PIN
* CLA = 0x80
* INS = 0x20
* P1 = 0x00
* P2 = 0x00
* Data = the PIN to be verified
* Response SW = 0x9000 on success, 0x63CX on failure, where X is the number of attempt remaining
* Preconditions: Secure Channel must be opened
Used to verify the user PIN. On correct PIN entry the card returns 0x9000, the retry counter is reset and the PIN is
marked as authenticated for the entire session (until the application is deselected or the card reset/teared). On
error, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is
returned. When the number of remaining retries reaches 0 the PIN is blocked. When the PIN is blocked this command
always returns 0x63C0, even if the PIN is inserted correctly.
### CHANGE PIN
* CLA = 0x80
* INS = 0x21
* P1 = 0x00
* P2 = 0x00
* Data = the new PIN
* Response SW = 0x9000 on success, 0x6A80 if the PIN format is invalid
* Preconditions: Secure Channel must be opened, user PIN must be verified
Used to change the user PIN. The new PIN must be composed of exactly 6 numeric digits. Should this be not the case,
the code 0x6A80 is returned. If the conditions matches the user PIN is updated and authenticated for the rest of
the session. The no-error SW 0x9000 is returned.
### UNBLOCK PIN
* CLA = 0x80
* INS = 0x22
* P1 = 0x00
* P2 = 0x00
* Data = the PUK followed by the new PIN
* Response SW = 0x9000 on success, 0x6A80 if the format is invalid
* Preconditions: Secure Channel must be opened, user PIN must be blocked
2017-10-09 12:06:59 +00:00
Used to unblock the user PIN. The data field must contain exactly 18 numeric digits, otherwise SW 0x6A80 is returned.
The first 12 digits are the PUK and the last 6 are the new PIN. If the PUK is correct the PIN is changed to the supplied
one, it is unblocked and authenticated for the rest of the session. The status code 0x9000 is returned. When the PUK is
wrong, the number of remaining retries is decreased and the SW 0x63CX, where X is the number of available retries is
2017-09-22 09:14:15 +00:00
returned. When the number of remaining retries reaches 0 the PUK is blocked. When the PUK is blocked this command
always returns 0x63C0, even if the PUK is inserted correctly. In this case the wallet is effectively lost.
2017-09-22 09:41:43 +00:00
2017-09-25 08:27:55 +00:00
### LOAD KEY
2017-09-22 09:41:43 +00:00
* CLA = 0x80
* INS = 0xD0
2017-10-09 12:06:59 +00:00
* P1 = key type
2017-09-25 08:27:55 +00:00
* P2 = 0x00
2017-09-22 09:41:43 +00:00
* Data = the key data
2017-10-09 12:06:59 +00:00
* Response SW = 0x9000 on success, 0x6A80 if the format is invalid, 0x6A86 if P1 is invalid, 0x6A81 if public key is
omitted and its derivation is not supported.
2017-09-22 09:41:43 +00:00
* Preconditions: Secure Channel must be opened, user PIN must be verified
2017-10-09 12:06:59 +00:00
P1:
* 0x01 = ECC SECP256k1 keypair
* 0x02 = ECC SECP256k1 extended keypair
* 0x03 = Binary seed as defined in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) (if card
supports public key derivation)
2017-09-25 07:53:20 +00:00
2017-10-09 12:06:59 +00:00
Data:
If P1 is 0x01 or 0x02
2017-09-25 08:27:55 +00:00
- Tag 0xA1 = keypair template
2017-10-09 12:06:59 +00:00
- Tag 0x80 = ECC public key component (can be omitted if card supports public key derivation)
2017-10-06 12:08:07 +00:00
- Tag 0x81 = ECC private key component
2017-10-09 12:06:59 +00:00
- Tag 0x82 = chain code (if P1=0x02)
If P1 is 0x03 a 64 byte sequence generated according to the BIP39 specifications is expected. The master key will be
generated according to the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) specifications. Since
2017-10-11 07:45:37 +00:00
in this case the public key is not provided externally, the card must support public key derivation.
2017-09-25 07:53:20 +00:00
This command is used to load or replace the keypair used for signing on the card. This command always aborts open
2017-10-09 12:06:59 +00:00
signing sessions, if any. Unless a DERIVE KEY is sent, a subsequent SIGN command will use this keypair for signature.
### DERIVE KEY
* CLA = 0x80
* INS = 0xD1
* P1 = 0x00
* P2 = 0x00
* Data = key derivation template
* Response SW = 0x9000 on success, 0x6A80 if the format is invalid, 0x6A81 if public keys are omitted and their derivation
is not supported.
2017-10-09 14:12:21 +00:00
* Preconditions: Secure Channel must be opened, user PIN must be verified, an extended keyset must be loaded
2017-10-09 12:06:59 +00:00
Data format:
- Tag 0xA2 = key derivation template
2017-10-09 14:12:21 +00:00
- Tag 0xC0 = a sequence of 32-bit integers (most significant byte first). Empty if the master key must be used.
- Tag 0xC1 = derived public key (omitted if master or public key derivation is supported)
- Tag 0xC2 = parent public key (omitted if master or public key derivation is supported)
2017-10-09 12:06:59 +00:00
This command is used before a signing session to generated a private key according to the [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
specifications. The generated key is used for all subsequent SIGN sessions. An empty 0x82 is used in order for SIGN to
use the master key instead. Omitting the 0x82 subtag entirely is not permitted.
### GENERATE MNEMONIC
* CLA = 0x80
* INS = 0xD2
* P1 = checksum size (between 4 and 8)
* P2 = 0x00
* Response SW = 0x9000 on success. 0x6A86 if P1 is invalid.
* Response Data = a sequence of 16-bit integers (most significant byte first).
* Preconditions: Secure Channel must be opened
Used to generate a mnemonic according to the algorithm specified in [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).
The returned data is a list of 16-byte integers which should be used as indexes in a wordlist to generate the
human-readable mnemonic. Each integer can have a value from 0 to 2047.
2017-09-25 07:53:20 +00:00
### SIGN
* CLA = 0x80
* INS = 0xC0
2017-10-04 12:10:59 +00:00
* P1 = data type
2017-09-25 07:53:20 +00:00
* P2 = segment flag
* Data = the data to sign
2017-10-06 12:08:07 +00:00
* Response = if P2 indicates last segment, the public key and the signature are returned
2017-09-25 07:53:20 +00:00
* Response SW = 0x9000 on success, 0x6A86 if P2 is invalid
* Preconditions: Secure Channel must be opened, user PIN must be verified, a valid keypair must be loaded
2017-10-04 12:10:59 +00:00
P1:
* 0x00 = transaction data
* 0x01 = precomputed hash
2017-09-25 07:53:20 +00:00
P2:
* bit 0 = if 1 first block, if 0 other block
* bit 1-6 = reserved
* bit 7 = if 0 more blocks, if 1 last block
2017-10-06 12:08:07 +00:00
Response Data format:
- Tag 0xA0 = signature template
- Tag 0x80 = ECC public key component
- Tag 0x30 = ECDSA Signature
- Tag 0x02 = R value
- Tag 0x02 = S value
2017-09-25 07:53:20 +00:00
Used to sign transactions. Since the maximum short APDU size is 255 bytes the transaction must be segmented before
being sent if it is larger than that. The overhead from the Secure Channel must be also accounted for. When the last
2017-09-30 14:26:06 +00:00
segment is sent, the card returns the calculated signature. The signature is an ECDSA signature calculated over the
2017-10-06 12:08:07 +00:00
SHA-256 hash of the sent data or directly over the provided hash if P1 = 0x01.
2017-09-25 07:53:20 +00:00
The P2 parameter is used to manage the signing session and is treated as a bitmask. The rightmost bit indicates whether
this block is the first one (1) or not (0). On the first block the card resets the signature state. The leftmost bit
indicates whether this is the last block (1) or not (0). On the last block, the card generates and sends the signatures
to the client.
For example, if a signing session spans over 3 segments, the value of P2 will be respectively 0x01, 0x00, 0x80. If
the signing session is composed of a single session P2 will have the value of 0x81.
After a signature is generated, the next SIGN command must have the rightmost bit of P2 set, otherwise 0x6A86 will
be returned.
2017-09-30 14:26:06 +00:00
This segmentation scheme allows resuming signature sessions if other commands must be sent in between and at
the same time avoid generating signatures over partial data, since both the first and the last block are marked.
On applet selection any pending signing session is aborted.
