General structure
The general structure of commands and responses is as follows:
Commands
| Field | Type | Content | Note |
|---|
| CLA | byte (1) | Application Identifier | 0x80 |
| INS | byte (1) | Instruction ID | |
| P1 | byte (1) | Parameter 1 | |
| P2 | byte (1) | Parameter 2 | |
| L | byte (1) | Bytes in payload | |
| PAYLOAD | byte (L) | Payload | |
Response
| Field | Type | Content | Note |
|---|
| ANSWER | byte (?) | Answer | depends on the command |
| SW1-SW2 | byte (2) | Return code | see list of return codes |
Return codes
| Return code | Description |
|---|
| 0x6400 | Execution Error |
| 0x6982 | Empty buffer |
| 0x6983 | Output buffer too small |
| 0x6986 | Command not allowed |
| 0x6D00 | INS not supported |
| 0x6E00 | CLA not supported |
| 0x6F00 | Unknown |
| 0x8000 | Success |
Command definition
GET_VERSION
Command
| Field | Type | Content | Expected |
|---|
| CLA | byte (1) | Application Identifier | 0x80 |
| INS | byte (1) | Instruction ID | 0x00 |
| P1 | byte (1) | Parameter 1 | ignored |
| P2 | byte (1) | Parameter 2 | ignored |
| L | byte (1) | Bytes in payload | 0 |
Response
| Field | Type | Content | Note |
|---|
| TEST | byte (1) | Test Mode | 0xFF means test mode is enabled |
| MAJOR | byte (2) | Version Major | 0..65535 |
| MINOR | byte (2) | Version Minor | 0..65535 |
| PATCH | byte (2) | Version Patch | 0..65535 |
| LOCKED | byte (1) | Device is locked | |
| SW1-SW2 | byte (2) | Return code | see list of return codes |
INS_GET_PUBLIC_KEY
Command
| Field | Type | Content | Expected |
|---|
| CLA | byte (1) | Application Identifier | 0x80 |
| INS | byte (1) | Instruction ID | 0x03 |
| P1 | byte (1) | Request User confirmation | No = 0 |
| P2 | byte (1) | Parameter 2 | ignored |
| LC | byte (1) | Bytes in payload | (depends) |
| Payload | byte (4) | Account ID | (depends) |
The account number is used to derive keys from BIP32 path 44'/283'/{'<'}account{'>'}'/0/0
(note that the account number is hardened as shown by the ' sign). Account number defaults
to 0x0 in the case of APDU with empty payload.
Response
| Field | Type | Content | Note |
|---|
| PublicKey | byte (65) | Public Key | |
| Address | byte (58) | Address | |
| SW1-SW2 | byte (2) | Return code | see list of return codes |
INS_SIGN_MSGPACK
Command
| Field | Type | Content | Expected |
|---|
| CLA | byte (1) | Application Identifier | 0x80 |
| INS | byte (1) | Instruction ID | 0x08 |
| P1 | byte (1) | Request User confirmation | (depends) |
| P2 | byte (1) | Parameter 2 | (depends) |
| LC | byte (1) | Bytes in payload | (depends) |
| Payload | byte (var) | AccID + MsgPack Chunks | (depends) |
If one single APDU may contain a whole transaction, P1 and P2 are both 0x00.
New format enhances messaging with an optional account number that must be inserted
in the first chunk of the sequence. As an optional payload, bit 0 of field P1 in
the first chunk must be set if present in the message.
And as for INS_GET_PUBLIC_KEY instruction, it is a big-endian encoded 32-bit
unsigned integer word.
The resulting sequence of chunks is as follows:
First APDU message
| CLA | INS | P1 | P2 | LC | Payload |
|---|
| 0x80 | 0x08 | 0x01 | 0x80 | N1 | account + MsgPack chunk #1 |
...
APDU message i
| CLA | INS | P1 | P2 | LC | Payload |
|---|
| 0x80 | 0x08 | 0x80 | 0x80 | Ni | MsgPack chunk #i |
...
Last APDU message
| CLA | INS | P1 | P2 | LC | Payload |
|---|
| 0x80 | 0x08 | 0x80 | 0x00 | NI | MsgPack chunk #I |
Response
| Field | Type | Content | Note |
|---|
| Signature | byte (64) | Signed message | |
| SW1-SW2 | byte (2) | Return code | see list of return codes |
If one signle APDU is needed for the whole transaction along with the account number,
P1 and P2 are 0x01 and 0x00 respectively.
| CLA | INS | P1 | P2 | LC | Payload |
|---|
| 0x80 | 0x08 | 0x01 | 0x00 | N1 | account + MsgPack txn |
If the account number is not inserted within the message, the former message format is used
(P1 in the first chunk is 0x00) and the account number defaults to 0x00 for the transaction
signature.
| CLA | INS | P1 | P2 | LC | Payload |
|---|
| 0x80 | 0x08 | 0x00 | 0x00 | N1 | MsgPack txn |
