From 3bb18078582c41ecf682d6e60ccb90b2bd5738c2 Mon Sep 17 00:00:00 2001 From: Coline Date: Tue, 5 Apr 2022 15:27:57 +0200 Subject: [PATCH] docs: apdu into .md --- doc/apdu.md | 550 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 550 insertions(+) create mode 100644 doc/apdu.md diff --git a/doc/apdu.md b/doc/apdu.md new file mode 100644 index 0000000..20954b4 --- /dev/null +++ b/doc/apdu.md @@ -0,0 +1,550 @@ +# APDU Documentation + + - [GET](#get) + - [GET APP CONFIGURATION](#get-app-configuration) + - [GET ETH PUBLIC ADDRESS](#get-eth-public-address) + - [GET ETH2 PUBLIC KEY](#get-eth2-public-key) + - [SIGN](#sign) + - [SIGN ETH TRANSACTION](#sign-eth-transaction) + - [SIGN ETH PERSONAL MESSAGE](#sign-eth-personal-message) + - [SIGN ETH EIP 712](#sign-eth-eip-712) + - [SET](#set) + - [SET EXTERNAL PLUGIN](#set-external-plugin) + - [SET PLUGIN](#set-plugin) + - [SET ETH2 WITHDRAWAL INDEX](#set-eth2-withdrawal-index) + - [Provide](#provide) + - [PROVIDE ERC 20 TOKEN INFORMATION](#provide-erc-20-token-information) + - [PROVIDE NFT INFORMATION](#provide-nft-information) + +
+
+
+ +## Global Instruction + +|Name|INS| +|----|---| +|[GET PUBLIC ADDRESS](#get-eth-public-address)|0x02| +|[SIGN](#sign-eth-transaction)|0x04| +|[GET APP CONFIGURATION](#get-app-configuration)|0x06| +|[SIGN PERSONAL MESSAGE](#sign-eth-personal-message)|0x08| +|[PROVIDE ERC 20 TOKEN INFORMATION](#provide-erc-20-token-information)|0x0A| +|[SIGN EIP 712 MESSAGE](#sign-eth-eip-712)|0x0C| +|[GET ETH2 PUBLIC KEY](#get-eth2-public-key)|0x0E| +|[SET ETH2 WITHDRAWAL INDEX](#set-eth2-withdrawal-index)|0x10| +|[SET EXTERNAL PLUGIN](#set-external-plugin)|0x12| +|[PROVIDE NFT INFORMATION](#provide-nft-information)|0x14| +|[SET PLUGIN](#set-plugin)|0x16| + +
+
+ +## GET + +### GET APP CONFIGURATION +
+ +Description + +This command returns specific application configuration + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|06|00|00|00|04| + +:inbox_tray: input data + +None + +:outbox_tray: output data + +|Description|Length| +|-----------|------| +|0x01 : arbitrary data signature enabled by user
0x02 : ERC 20 Token information needs to be provided externally|1| +|Application major version|1| +|Application minor version|1| +|Application patch version|1| +
+ +
+ +### GET ETH PUBLIC ADDRESS + +
+ +Description + +This command returns the public key and Ethereum address for the given BIP 32 path. +The address can be optionally checked on the device before being returned. + +Usefull link: +- [HD Wallet by ledger](https://www.ledger.com/academy/crypto/what-are-hierarchical-deterministic-hd-wallets) +- [BIP-044](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) + +|CLA|INS|P1 |P2 |Lc |Le | +|---|---|-------------------------------------------------|--------------------------------|----------|----------| +|E0 |02 |00 : return address |00: do not return the chain code| variable | variable | +| | |01 : display address and confirm before returning|01 : return the chain code| | | | + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Number of BIP 32 derivations to perform (max 10)| 1| +|First derivation index (big endian)| 4| +| ... | 4| +| Last derivation index (big endian) | 4| + +:outbox_tray: output data + +|Description|Length| +|-----------|------| +|Public Key length|1| +|Uncompressed address length|var| +|Ethereum address length|1| +|Ethereum address|var| +|Chain code if requested|32| + +Exemple: +With path `"44'/60'/1'/0/0"` + +CLA: E0 +INS: 02 +P1 : 00 +P2 : 00 +Lc : 11 (17 in hex) +Le : + - 04 (number BIP 32 derivations) + - 80 00 00 2c + - 80 00 00 3C + - 00 00 00 00 + - 00 00 00 00 + +|CLA|INS|P1|P2|Lc|Le - BIP number|First derivation|Second derivation|Third derivation|Fourth derivation| +|-|-|-|-|-|-|-|-|-|-| +| | | | | | |`44'` |`60'` |`0` |`0` | +|E0|02|00|00|11|04|8000002C|8000003C|00000000|00000000| + +-> E0 02 00 00 11 04 8000002C 8000003C 00000000 00000000 + +
+ +
+ +### GET ETH2 PUBLIC KEY + +
+ +Description + +This command returns an Ethereum 2 BLS12-381 public key derived following EIP 2333 specification (https://eips.ethereum.org/EIPS/eip-2333) + +This command has been supported since firmware version 1.6.0 + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|0E|00 : return public key|00|variable|variable| +|||01 : display public key and confirm before returning|||| +||||||| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Number of BIP 32 derivations to perform (max 10)|1| +|First derivation index (big endian)|4| +|...|4| +|Last derivation index (big endian)|4| + +:outbox_tray: output data + +|Description|Length| +|-----------|------| +|Public key|48| +
+ + +
+
+
+ +## SIGN + +### SIGN ETH TRANSACTION + +
+ +Description + +This command signs an Ethereum transaction after having the user validate the following parameters + + - Gas price + - Gas limit + - Recipient address + - Value + +The input data is the RLP encoded transaction, without v/r/s present, streamed to the device in 255 bytes maximum data chunks. + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|04|00 : first transaction data block|00|variable|variable| +|||80 : subsequent transaction data block|||| +||||||| + +:inbox_tray: input data (first transaction data block) + +|Description|Length| +|-----------|------| +|Number of BIP 32 derivations to perform (max 10)|1| +|First derivation index (big endian)|4| +|...|4| +|Last derivation index (big endian)|4| +|RLP transaction chunk|variable| + +:inbox_tray: input data (other transaction data block) + +|Description|Length| +|-----------|------| +|RLP transaction chunk|variable| + +:outbox_tray: output data + +|Description|Length| +|-----------|------| +|v|1| +|r|32| +|s|32| + +
+ +
+ +### SIGN ETH PERSONAL MESSAGE + +
+ +Description + +This command signs an Ethereum message following the personal_sign specification (https://github.com/ethereum/go-ethereum/pull/2940) after having the user validate the SHA-256 hash of the message being signed. + +This command has been supported since firmware version 1.0.8 + +The input data is the message to sign, streamed to the device in 255 bytes maximum data chunks + + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|08|00 : first message data block|00|variable|variable| +|||80 : subsequent message data block|||| +||||||| + +:inbox_tray: input data (first message data block) + +|Description|Length| +|-----------|------| +|Number of BIP 32 derivations to perform (max 10)|1| +|First derivation index (big endian)|4| +|...|4| +|Last derivation index (big endian)|4| +|Message length|4| +|Message chunk|variable| + +:inbox_tray: input data (other transaction data block) + +|Description|Length| +|-----------|------| +|Message chunk|variable| + +:outbox_tray: output data + +|Description|Length| +|-----------|------| +|v|1| +|r|32| +|s|32| + +
+ +
+ +### SIGN ETH EIP 712 + +
+ +Description + +This command signs an Ethereum message following the EIP 712 specification (https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md) + +For implementation version 0, the domain hash and message hash are provided to the device, which displays them and returns the signature + +This command has been supported since firmware version 1.5.0 + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|0C|00|implementation version: 00|variable|variable| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Number of BIP 32 derivations to perform (max 10)|1| +|First derivation index (big endian)|4| +|...|4| +|Last derivation index (big endian)|4| +|Domain hash|32| +|Message hash|32| + +:outbox_tray: output data + +|Description|Length| +|-----------|------| +|v|1| +|r|32| +|s|32| + +
+ +
+
+
+ +## SET + +### SET EXTERNAL PLUGIN + +
+ +Description + +This commands provides the name of a trusted binding of a plugin with a contract address and a supported method selector. This plugin will be called to interpret contract data in the following transaction signing command. + +It shall be run immediately before performing a transaction involving a contract supported by this plugin to display the proper information to the user if necessary. + +The function returns an error sw (0x6984) if the plugin requested is not installed on the device, 0x9000 otherwise. + +The signature is computed on + +len(pluginName) || pluginName || contractAddress || methodSelector + +signed by the following secp256k1 public key 0482bbf2f34f367b2e5bc21847b6566f21f0976b22d3388a9a5e446ac62d25cf725b62a2555b2dd464a4da0ab2f4d506820543af1d242470b1b1a969a27578f353 + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|12|00|00|variable|00| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Length of plugin name|1| +|plugin name|variable| +|contract address|20| +|method selector|4| +|signature|variable| + +:outbox_tray: output data + +None + +
+ +
+ +### SET PLUGIN + +
+ +Description + +This commands provides the name of a trusted binding of a plugin with a contract address and a supported method selector. This plugin will be called to interpret contract data in the following transaction signing command. + +It can be used to set both internal and external plugins. + +It shall be run immediately before performing a transaction involving a contract supported by this plugin to display the proper information to the user if necessary. + +The function returns an error sw (0x6984) if the plugin requested is not installed on the device, 0x9000 otherwise. + +The plugin names `ERC20`, `ERC721` and `ERC1155` are reserved. Additional plugin names might be added to this list in the future. + +The signature is computed on + +type || version || len(pluginName) || pluginName || address || selector || chainId || keyId || algorithmId || len(signature) || signature + + + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|16|00|00|variable|00| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Type|1| +|Version|1| +|Plugin Name Length|1| +|Plugin Name|variable| +|Address|20| +|Selector|4| +|Chain ID|8| +|KeyID|1| +|Algorithm|1| +|Signature Length|1| +|Signature|variable| + +:outbox_tray: output data + +None + +
+ +
+ +### SET ETH2 WITHDRAWAL INDEX + +
+ +Description + +This command sets the index of the Withdrawal key used as withdrawal credentials in an ETH2 deposit contract call signature. The path of the Withdrawal key is defined as m/12381/3600/index/0 according to EIP 2334 (https://eips.ethereum.org/EIPS/eip-2334) + +The default index used is 0 if this method isn’t called before the deposit contract transaction is sent to the device to be signed + +This command has been supported since firmware version 1.5.0 + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|10|00|00|variable|variable| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Withdrawal key index (big endian)|4| + +:outbox_tray: output data + +None + +
+ +
+
+
+ +## Provide + +### PROVIDE ERC 20 TOKEN INFORMATION + +
+ +Description + +This commands provides a trusted description of an ERC 20 token to associate a contract address with a ticker and number of decimals. + +It shall be run immediately before performing a transaction involving a contract calling this contract address to display the proper token information to the user if necessary, as marked in GET APP CONFIGURATION flags. + +The signature is computed on + +ticker || address || number of decimals (uint4be) || chainId (uint4be) + +signed by the following secp256k1 public key 0482bbf2f34f367b2e5bc21847b6566f21f0976b22d3388a9a5e446ac62d25cf725b62a2555b2dd4This command returns an Ethereum 2 BLS12-381 public key derived following EIP 2333 specification (https://eips.ethereum.org/EIPS/eip-2333) + +This command has been supported since firmware version 1.6.064a4da0ab2f4d506820543af1d242470b1b1a969a27578f353 + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|0A|00|00|variable|00| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Length of ERC 20 ticker|1| +|ERC 20 ticker|variable| +|ERC 20 contract address|20| +|Number of decimals (big endian encoded)|4| +|Chain ID (big endian encoded)|4| +|Token information signature|variable| + +:outbox_tray: output data + +none + +
+ +
+ +### PROVIDE NFT INFORMATION + +
+ +Description + +This commands provides a trusted description of an NFT to associate a contract address with a collectionName. + +It shall be run immediately before performing a transaction involving a contract calling this contract address to display the proper nft information to the user if necessary, as marked in GET APP CONFIGURATION flags. + +The signature is computed on: + +type || version || len(collectionName) || collectionName || address || chainId || keyId || algorithmId + +|CLA|INS|P1|P2|Lc|Le| +|---|---|--|--|--|--| +|E0|14|00|00|variable|00| + +:inbox_tray: input data + +|Description|Length| +|-----------|------| +|Type|1| +|Version|1| +|Collection Name Length|1| +|Collection Name|variable| +|Address|20| +|Chain ID|8| +|KeyID|1| +|Algorithm ID|1| +|Signature Length|1| +|Signature|variable| + +:outbox_tray: output data + +None + +
+ +
+
+
+ +[//]: # (## Command name) +[//]: # () +[//]: # (
) +[//]: # () +[//]: # (Description ) +[//]: # () +[//]: # () +[//]: # (|CLA|INS|P1|P2|Lc|Le|) +[//]: # (|---|---|--|--|--|--|) +[//]: # (|||||||) +[//]: # (|||||||) +[//]: # (|||||||) +[//]: # () +[//]: # (:inbox_tray: input data) +[//]: # () +[//]: # (|Description|Length|) +[//]: # (|-----------|------|) +[//]: # (|||) +[//]: # (|||) +[//]: # (|||) +[//]: # () +[//]: # (:outbox_tray: output data) +[//]: # () +[//]: # (|Description|Length|) +[//]: # (|-----------|------|) +[//]: # (|||) +[//]: # (|||) +[//]: # (|||) +[//]: # () +[//]: # (
) \ No newline at end of file