Skip to content

APDUSPEC.md

Latest commit

 

History

History
407 lines (300 loc) · 15.7 KB

APDUSPEC.md

File metadata and controls

407 lines (300 loc) · 15.7 KB

Oasis App

General structure

The Application Identifier depends on the app type:

Type APP_CLA
Validator 0xf5
Consumer 0x05

The general structure of commands and responses is as follows:

Commands

Field Type Content Note
CLA byte (1) Application Identifier APP_CLA
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
0x6985 Conditions not satisfied
0x6986 Command not allowed
0x6D00 INS not supported
0x6E00 CLA not supported
0x6F00 Unknown
0x9000 Success

Command definition

GET_VERSION

Command

Field Type Content Expected
CLA byte (1) Application Identifier APP_CLA
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 (1) Version Major
MINOR byte (1) Version Minor
PATCH byte (1) Version Patch
LOCKED byte (1) Device is locked
SW1-SW2 byte (2) Return code see list of return codes

GET_ADDR_ED25519

Command

Field Type Content Expected
CLA byte (1) Application Identifier APP_CLA
INS byte (1) Instruction ID 0x01
P1 byte (1) Request User confirmation No = 0
P2 byte (1) Parameter 2 ignored
L byte (1) Bytes in payload (depends)
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 474
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

First three items in the derivation path will be hardened automatically hardened

Response

Field Type Content Note
PK byte (32) Public Key
ADDR byte (??) Bech 32 addr
SW1-SW2 byte (2) Return code see list of return codes

SIGN_ED25519

Command

Field Type Content Expected
CLA byte (1) Application Identifier APP_CLA
INS byte (1) Instruction ID 0x02
P1 byte (1) Payload desc 0 = init
1 = add
2 = last
P2 byte (1) ---- not used
L byte (1) Bytes in payload (depends)

The first packet/chunk includes only the derivation path

All other packets/chunks should contain message to sign

The chunk size is 250 bytes.

First Packet

Field Type Content Expected
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 474
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

Other Chunks/Packets

Field Type Content Expected
Data bytes... Context+Message

Data is defined as:

Field Type Content Expected
CtxLen byte Context Length
Context bytes.. Context CtxLen bytes
Message bytes.. CBOR data to sign

Response

The response depends on app type:

Consumer Response

Field Type Content Note
SIG byte (64) Signature
SW1-SW2 byte (2) Return code see list of return codes

Validator Response

The Validator response has a validation flow that can result in diferente responses:

If Oasis Blob is a Consensus Type:

  1. Vote State is checked and if it is not initialized, a new valid vote is set:
Field Type Content Note
SW1-SW2 byte (2) Return code see list of return codes
  1. Vote is initialized and the current vote state is returned alongside the conflicting vote data [vote][vote_state][error]
Field Type Content Note
Buffer byte (1) Vote type
byte (8) Vote height
byte (8) Vote round
byte (1) Vote state type
byte (8) Vote state height
byte (8) Vote state round
SW1-SW2 byte (2) Return code see list of return codes

If Oasis Blob is not a Consensus Type:

Field Type Content Note
SIG byte (64) Signature
SW1-SW2 byte (2) Return code see list of return codes

SIGN_RT_ED25519

Command

Field Type Content Expected
CLA byte (1) Application Identifier 0x05
INS byte (1) Instruction ID 0x05
P1 byte (1) Payload desc 0 = init
1 = add
2 = last
P2 byte (1) ---- not used
L byte (1) Bytes in payload (depends)

The first packet/chunk includes only the derivation path

All other packets/chunks should contain message to sign

The chunk size is 250 bytes.

First Packet

Field Type Content Expected
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 474
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

Other Chunks/Packets

Field Type Content Expected
Data bytes... Context+Message

Data is defined as:

Field Type Content Expected
Meta byte.. CBOR metadata
Message bytes.. CBOR data to sign

Meta contains the following fields:

  • runtime_id: 32-byte runtime ID
  • chain_context: 32-byte chain ID
  • orig_to (optional): 20-byte ethereum destination address

Response

Field Type Content Note
SIG byte (64) Signature
SW1-SW2 byte (2) Return code see list of return codes

GET_ADDR_SECP256K1

Command

Field Type Content Expected
CLA byte (1) Application Identifier 0x05
INS byte (1) Instruction ID 0x04
P1 byte (1) Request User confirmation No = 0
P2 byte (1) Parameter 2 ignored
L byte (1) Bytes in payload (depends)
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 60
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

First three items in the derivation path are hardened

Response

Field Type Content Note
PK byte (33) Compressed Public Key
ADDR byte (??) Hex addr
SW1-SW2 byte (2) Return code see list of return codes

SIGN_RT_SECP256K1

Command

Field Type Content Expected
CLA byte (1) Application Identifier 0x05
INS byte (1) Instruction ID 0x07
P1 byte (1) Payload desc 0 = init
1 = add
2 = last
P2 byte (1) ---- not used
L byte (1) Bytes in payload (depends)

The first packet/chunk includes only the derivation path

All other packets/chunks should contain message to sign

First Packet

Field Type Content Expected
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 60
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

Other Chunks/Packets

Field Type Content Expected
Data bytes... Meta+Message

Data is defined as:

Field Type Content Expected
Meta byte.. CBOR metadata
Message bytes.. CBOR data to sign

Meta contains the following fields:

  • runtime_id: 32-byte runtime ID
  • chain_context: 32-byte chain ID
  • orig_to (optional): 20-byte ethereum destination address

Response

Field Type Content Note
SIG byte (64) Signature
SW1-SW2 byte (2) Return code see list of return codes

GET_ADDR_SR25519

Command

Field Type Content Expected
CLA byte (1) Application Identifier 0x05
INS byte (1) Instruction ID 0x03
P1 byte (1) Request User confirmation No = 0
P2 byte (1) Parameter 2 ignored
L byte (1) Bytes in payload (depends)
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 474
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

First three items in the derivation path are hardened

Response

Field Type Content Note
PK byte (32) Public Key
ADDR byte (??) Bech 32 addr
SW1-SW2 byte (2) Return code see list of return codes

SIGN_RT_SR25519

Command

Field Type Content Expected
CLA byte (1) Application Identifier 0x05
INS byte (1) Instruction ID 0x06
P1 byte (1) Payload desc 0 = init
1 = add
2 = last
P2 byte (1) ---- not used
L byte (1) Bytes in payload (depends)

The first packet/chunk includes only the derivation path

All other packets/chunks should contain message to sign

First Packet

Field Type Content Expected
Path[0] byte (4) Derivation Path Data 44
Path[1] byte (4) Derivation Path Data 474
Path[2] byte (4) Derivation Path Data ?
Path[3] byte (4) Derivation Path Data ?
Path[4] byte (4) Derivation Path Data ?

Other Chunks/Packets

Field Type Content Expected
Data bytes... Meta+Message

Data is defined as:

Field Type Content Expected
Meta byte.. CBOR metadata
Message bytes.. CBOR data to sign

Meta contains the following fields:

  • runtime_id: 32-byte runtime ID
  • chain_context: 32-byte chain ID
  • orig_to (optional): 20-byte ethereum destination address

Response

Field Type Content Note
SIG byte (64) Signature
SW1-SW2 byte (2) Return code see list of return codes