Skip to main content
Zondax Github LinkZondax Github Link
Theme SwitchTheme Switch

APDU protocol description

This document aims to provide a description of the APDU protocol supported by the app, explaining what each instruction does, the expected parameters and return values

General Structure

The general structure of a reqeuest and response is as follows:

Request / Command

FieldTypeContentNote
CLAbyte (1)Application Identifier0xFF, To be determined
INSbyte (1)Instruction ID
P1byte (1)Parameter 1
P2byte (1)Parameter 2
Lbyte (1)Bytes in payload
PAYLOADbyte (L)Payload

Response

FieldTypeContentNote
ANSWERbyte (?)Answerdepends on the command
SW1-SW2byte (2)Return codesee list of return codes

Return codes

Return codeDescription
0x6400Execution Error
0x6982Empty buffer
0x6983Output buffer too small
0x6986Command not allowed
0x6D00INS not supported
0x6E00CLA not supported
0x6F00Unknown
0x9000Success

Commands definitions

GetVersion

This command will return the app version

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier
INSbyte (1)Instruction ID0x00
P1byte (1)Parameter 1ignored
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0

Response

FieldTypeContentNote
TESTbyte (1)Test Mode0xFF means test mode is enabled
MAJORbyte (1)Version Major
MINORbyte (1)Version Minor
PATCHbyte (1)Version Patch
LOCKEDbyte (1)Device is locked
TARGET IDbyte (4)Target ID
SW1-SW2byte (2)Return codesee list of return codes

GetAddress

This command returns the public key corresponding to the secret key found at the given bip32 path, see below.

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier
INSbyte (1)Instruction ID0x01
P1byte (1)Request User confirmationNo = 0
P2byte (1)ignored
Lbyte (1)Bytes in payload(depends)
PathNbyte (1)Number of path components? (typically 4)
Path[0]byte (4)Derivation Path Data0x80000A55
Path[1]byte (4)Derivation Path Data0xA2862AD3
Path[2]byte (4)Derivation Path Data?
Path[3]byte (4)Derivation Path Data?
Path[4]byte (4)Derivation Path Data?

Response

FieldTypeContentNote
PK_LENbyte (1)Bytes in PKEY
PKEYbyte (??)Public key bytes
SW1-SW2byte (2)Return codesee list of return codes

Sign

This command will return a signature of the passed payload hashed with SHA256

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier
INSbyte (1)Instruction ID0x02
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)ignored
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

All other packets/chunks contain data chunks that are described below

First Packet

FieldTypeContentExpected
PathNbyte (1)Number of path components? (typically 4)
Path[0]byte (4)Derivation Path Data0x80000A55
Path[1]byte (4)Derivation Path Data0xA2862AD3
Path[2]byte (4)Derivation Path Data?
Path[3]byte (4)Derivation Path Data?
Path[4]byte (4)Derivation Path Data?

Other Chunks/Packets

FieldTypeContentExpected
Databytes...Message

Data is defined as:

FieldTypeContentExpected
Messagebytes..Data to sign

Response

FieldTypeContentNote
SIG_HASHbyte (32)Signed hashSHA256 hash used as signature message
SIGbyte (65)SignatureRSV encoded signature
SW1-SW2byte (2)Return codesee list of return codes