1. Ledger Wallet 1 - 1.0 ("Ledger" release - 30th of March 2015)

  • [enh] New unified multiplatform / multibearer firmware

  • [bev] Update GET FIRMWARE VERSION to return device features

  • [bev] Replace wipe PIN by random seed PIN

  • [bev] Add an option to use the second factor permanently on SET OPERATION MODE and retrieve the second factor in use on GET OPERATION MODE (Ledger Wallet mode)

  • [enh] Rename SET KEYMAP to SET KEYBOARD CONFIGURATION and configure typing parameters

  • [sec] Erase the dongle after 30 invalids second factor attempts

  • [enh] Optional OP_RETURN payload in UNTRUSTED HASH TRANSACTION INPUT FINALIZE

  • [enh] Alternate coin versions : SET ALTERNATE COIN VERSIONS

  • [enh] Alternate second factor updates : SET USER KEYCARD APDU, SETUP SECURE SCREEN APDU

  • [enh] Personal BIP 70 certificates : STORE TRUST ROOT BIP 70, CREATE CERTIFICATE BIP 70, CREATE PAYMENT REQUEST BIP 70, PROCESS CERTIFICATE BIP 70, PARSE PAYMENT REQUEST BIP 70, UNTRUSTED HASH TRANSACTION INPUT FINALIZE FULL BIP 70, FACTORY INITIALIZE BIP 70 TRUST ROOT

2. 1.4.13 ("Ledger is coming" release - 17th of November 2014)

  • [bev] Modify the keycard second factor to only check the address

  • [bev] Enable the keycard second factor with a specific APDU at boot time

3. 1.4.12 ("Speedy Rabbit Hotfix 1" release - 28th of October 2014)

4. 1.4.11 ("Speedy Rabbit" release - 27th of October 2014)

  • [enh] Improve SHA 512 and modular multiplication speed

  • [enh] Modify SETUP to include a One Time Pad generated by the customer

  • [enh] Let Windows users replay a second factor by triggering num lock or scroll lock

  • [sec] Verify that the provided SETUP FORWARD ECDH public key belongs to the curve

5. 1.4.10 ("Battleship 2" release - 8th of September 2014)

  • [bug] Fix second factor spurious trigger bug added in 1.4.9

6. 1.4.9 ("Battleship" release - 27th of August 2014)

  • [enh] Provide an option to replace the second factor by a key card

  • [enh] Add supported and current operation modes in firmware attestation

  • [enh] Dump the seed on every other insertion until the PIN is entered

  • [enh] Add number of remaining attempts on VERIFY PIN

  • [enh] Return Y parity on signature to save key recovery time (as per FSV https://github.com/antonio-fr/Fast_Sign_Verify - Antoine Ferron)

  • [enh] Make sure that the returned signatures are canonical (as per https://ripple.com/wiki/Transaction_Malleability)

  • [sec] Only dump the trusted input and developer wrapping keys in SETUP if developer mode is supported

  • [tmp] Temporarily disable the COMPOSE M OF N ADDRESS command due to lack of space

7. 1.4.8 ("Greenaddress" release - 05th of August 2014)

  • [enh] Allow 64 bytes seed in SETUP (BIP39 compliance)

  • [enh] Return the BIP32 chain code along with the public key in GET WALLET PUBLIC KEY

  • [enh] Add 0xB11E derivation path allowing a message signature without second factor and without power cycling, scan the low end word of derivation path components only

  • [bug] Remove user entropy in SETUP (not used properly and no buffer space left to type it along with a 64 bytes seed)

  • [bug] Allow 0 derivations in BIP32 derivation path

8. 1.4.7 (private release, open second factor - 23rd of July 2014)

  • [enh] Add a mode to skip the second factor if consuming from P2SH inputs

  • [enh] Allow derivation from an arbitrary BIP 32 path

  • [enh] Return Loader ID in firmware information

9. 1.4.6 ("Maison du Bitcoin" hackathon - 15th of June 2014)

  • [enh] Point Of Sale mode for setup and seed recovery

  • [enh] Allow message signature without confirmation for arbitrary BitID chain

10. 1.4.5 ("Maison du Bitcoin" meetup - 4th of June 2014)

  • [bug] Fix keyboard LED detection on OSX (infinite waiting loop)

  • [bug] Fix firmware diversification

  • [bug] Fix generic HID transport

11. 1.4.4 ("Maison du Bitcoin" opening release - 13th of May 2014)

  • [bug] Fix BIP32 implementation regarding hardneded / non hardened keys

  • [enh] Implement missing 1.4.3 features

  • [enh] Type the seed using the second factor

  • [enh] Add firmware version in attestation

  • [enh] Restrict signature hashtypes on setup

  • [enh] Provide forward setup for prepaid dongles scenarios

  • [enh] Secure screen mode for Prismicide prototype

12. 1.4.3 (30c3 failed release :p - 20th of March 2014 Paymium Meetup release)

  • [enh] full redesign : HD Wallet (BIP 32), Keyboard confirmation, server and partial transactions APIs

13. 1.4.2 (Bitcoin 2013 release)

  • [enh] New security rules & operation modes

14. 1.4.1 (private release)

  • [enh] ECC operations speed-up

  • [bug] Private key are now paired to their curve parameters (cheers Jix :p)

15. 1.4.0 (29c3 release)

  • Initial release

16. About

This specification describes the common functionalities of Ledger applications dedicated to secure bitcoin transactions. Such application performs all sensitive cryptographic operations related to a bitcoin transaction (key generation & signature) onboard, and helps protecting against malware in an untrusted environment by controlling the signed data.

The first supported device is Ledger Wallet, a USB smartcard/dongle.

Other devices can offer additional functionalities, such as a screen, buttons, different transport bearers or split functionalities between different hardware components leading to some differences in commands processing. Those differences are highlited in this common document and described more specifically in the dedicated device specification.

17. User validation mode

Ledger Wallet allows you to validate what you sign - i.e. check that you are paying the right amount to the right destination. The following User validation methods are available

17.1. Keyboard User validation

This method is the original scheme introduced in version 1.4.3 - it is the default method available when operating in legacy BTChip mode

User validation is performed as follows :

  • A specific status is returned to inform the user that a validation is pending

  • The user unplugs the dongle

  • The user plugs the dongle back into the computer (or a different computer / smartphone, tablet with USB host support, depending on how confident you are about the first computer integrity)

  • The dongle "types" (as a keyboard) a summary of the action to be validated and a 4 digits PIN to be entered, which is unique to the transaction

  • The user plugs the dongle back into the first computer (or just unplugs / plugs it again)

  • The user enters the PIN to confirm user validation

Note
 Devices offering a screen and buttons do not support this validation mode

17.2. Security Card User validation

This user validation mode has been introduced in version 1.4.9 and provides an option to validate a transaction destination using a printed card for easier validation.

User validation is performed as follows :

  • A specific status is returned to inform the user that a validation is pending. This request includes random indexes in the address to match against the printed card

  • The user types the result matching the random indexes in the printed card to confirm user validation

This user validation method should be used with caution as a malware would be able to gather information from each unique Security Card after enough transactions are signed. It is recommended to only use it to pair an secure screen as described later or to print a new card after a few (around 10) transactions have been performed.

Note
 Devices offering a screen and buttons do not support this validation mode

17.3. Secure Screen User validation

This user validation mode has been introduced in version LW1-1.0 and provides an option to validate a transaction destination and amount using a paired device with a screen

User validation is performed as follows :

  • A specific status is returned to inform the user that a validation is pending. This request includes an encrypted summary of the transaction and a nonce. The symmetric encryption keys are shared when the Ledger Wallet and the remote device are paired. A Security Card challenge is requested to pair the remote device

  • The user verifies the transaction summary on the remote device

  • The remote device generates a signed version of the nonce which is sent to the Ledger Wallet to confirm user validation

Note
 Devices offering a screen and buttons managed by the secure part of the device do not support this validation mode

17.4. Personal BIP 70 Certificates User validation

This user validation mode has been introduced in version LW-1.0 and provides an option to validate a transaction destination and amount against a BIP 70 request.

The process is initiated as follows when performed between two Ledger Wallet users :

  • A dedicated identity is created by the sender using the CREATE CERTIFICATE BIP 70 APDU, bound to a BIP 32 derivation path. This certificate is signed by a root certificate set at personalization time using the FACTORY INITIALIZE BIP 70 TRUST ROOT APDU or at runtime using the STORE TRUST ROOT BIP 70 APDU. All Ledger Wallet dongles are factory initialized with a shared root certificate in slot 0.

  • This identity is shared with the receiver, which validates it using its provided checksum and accepts it using the PROCESS CERTIFICATE BIP 70 APDU.

A transaction is processed as follows :

  • The sender creates a BIP 70 Payment Request associated to an identity and a BIP 32 derivation path related to this identity using the CREATE PAYMENT REQUEST BIP 70 APDU.

  • The payment request is processed by the receiver using the PARSE PAYMENT REQUEST BIP 70 APDU and a transaction is formatted using the regular methods, then finalized with the UNTRUSTED HASH TRANSACTION INPUT FINALIZE FULL BIP 70 APDU.

External consumers of this BIP 70 Payment Request can choose to trust its destination request if signed by the Ledger Wallet shared root certificate.

Note
 Currently the certificates and BIP 70 Payment Request are generated over secp256k1, which is not compatible with BitcoinJ

18. Operation modes

Operation modes define which operations are allowed given the security environment the dongle is operating in.

Four operation modes are defined :

  • standard-wallet mode, managing an HD Wallet (BIP 32) with multiple accounts, supporting payments to a single address and enforcing user validation of the full transaction (unless the wallet is setup as a second factor for P2SH transactions). This mode is intended for all bitcoin users.

  • relaxed-wallet mode, managing an HD Wallet with multiple accounts, supporting arbitrary payments and enforcing user validation of the amount spent. This mode is intended for bitcoin users interested in drafting custom transactions with some level of control.

  • server mode, managing an HD Wallet with multiple accounts, supporting arbitrary payments and enforcing pre defined limits on the amount spent. This mode is intended for server operators using one or several Ledger Wallet dongles to secure their hot wallets.

  • developer mode, managing BIP 32 or regular private keys and allowing to sign arbitrary data. This mode is intended for bitcoin power users drafting custom transactions and only interested in private keys protection.

The dongle initally operates in standard-wallet mode when received (if this mode is enabled). The last chosen mode is restored when the dongle is powered on.

18.1. standard-wallet mode

Only a single point-to-point output (i.e. the standard script or a P2SH script) along with one change address is authorized.

All transaction inputs are controlled by the dongle.

The change address index is automatically handled by the dongle and increased for each transaction to prevent address reuse. The change address index is shared for all accounts.

The standard script is coded as

OP_DUP OP_HASH160 [pubKeyHash] OP_EQUALVERIFY OP_CHECKSIG

A P2SH script is coded as

OP_HASH160 [script hash] OP_EQUAL

Transaction are controlled by the user validation process. The following data will be prompted to the user :

  • Amount to pay

  • Change amount

  • Fees

18.2. relaxed-wallet mode

Arbitrary output is authorized

Transaction inputs are only controlled if they use a key actually belonging to a wallet account.

Transaction are controlled by the user validation process. The following data will be prompted to the user :

  • Amount to pay

  • A large warning that relaxed-wallet mode is in use

18.3. server mode

Arbitrary output is authorized

Transaction inputs are only controlled if they use a key actually belonging to a wallet account.

Transactions are controlled given user parameters and automatically signed if accepted.

Transactions can be controlled on a combination of the following parameters :

  • A cumulative maximum amount used in transactions

  • A maximum number of consecutive transactions before the dongle is removed

18.4. developer mode

Arbitrary data can be signed in this mode

Keys used in developer mode cannot be used in a different mode

19. Lifecycle management APDUs

19.1. SETUP

19.1.1. Description

This command is used to setup the dongle when received, or pre-issuance when using the forward setup mode. It must be executed on a trusted computer as security critical data is exchanged.

For a new dongle not used as a backup device, a regular user will create a new random seed for a HD wallet and a PIN.

The PIN is used to perform a new payment transaction - it is sent as cleartext to the dongle and is not intended to be used as a malware protection method, only as an anti theft security. When generating a new seed in regular setup mode, the dongle types it on every other powerup until the PIN is entered, finishing with an X to mark the end of the seed. It is recommended to do this on a different computer / device for maximum security before backing it up.

Warning
 When getting the seed backup, the string must begin with "Seed ", end with an X and be exactly 128 hexadecimal digits long (64 bytes). If not, you’re missing either the beginning or the end of the seed and should retry until you see the whole seed.

In Point Of Sale setup mode, a PIN is exchanged between the user and the dongle. The seed is generated but not typed, and can be recovered through GET POINT OF SALE SEED commands. Until the encrypted seed is recovered, GET WALLET PUBLIC KEY is enabled without needing to enter the PIN. This mode is typically used for a service (such as a physical counter) offering prepaid dongles with KYC procedures and wanting to deliver a physical backup of the seed.

In forward setup mode, a secret PIN and a secret One Time Pad are exchanged between the user and the dongle. The seed is generated but not typed, and only GET WALLET PUBLIC KEY is enabled, without needing to enter the PIN. It is returned encrypted by the One Time Pad, so that only the user who generated the One Time Pad can decrypt it, and also typed after the first PIN entry. This mode is typically used for a service (such as a web shop or a vending machine) offering prepaid dongles and willing to provide the seed to the end user without compromising the security of the transactions.

After SETUP is performed, the dongle has to be reset to wipe out all parameters and start again - this can be achieved by entering the wrong PIN 3 times in a row.

A secondary PIN can be provided for plausible deniability - when entered instead of the regular user PIN, a random seed generated during setup is used for this session. This seed should not be used to store any important amount as it is erased when the dongle is reset.

It is recommended to store the BIP32 seed returned in the output of the SETUP command in a safe location for backup purposes - typically GPG encrypt it to yourself and store it on multiple storage devices / clouds.

During setup, two random BIP 70 3DES-2 encryption and signature keys are generated.

The coin regular version and P2SH versions can be changed dynamically during a card session. They are initialized with the versions provided in the setup command at boot time.

Note
 Devices offering a screen and buttons will override the seed backup and PIN parameters to let the user enter it directly on device. Dummy values should be used from the caller.

19.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

20

00 : regular setup

02 : Point Of Sale setup

80 : forward setup

00 : when used in forward setup mode, type the seed on the first successful PIN entry

01 : when used in forward setup, do not type the seed on the first successful PIN entry

var

var

Input data (regular setup)

Description

Length

Bitflag of supported operation modes

0x01 : wallet mode

0x02 : relaxed wallet mode

0x04 : server mode

0x08 : developer mode

1

Bitflag of features

0x01 : use uncompressed public keys in addresses (otherwise compress them)

0x02 : enable RFC 6979 deterministic signatures (otherwise use a random K)

0x04 : authorize all signature hashtypes (otherwise only authorize SIGHASH_ALL)

0x08 : skip second factor, allow relaxed inputs and arbitrary ouput scripts if consuming P2SH inputs in a transaction

1

Coin version accepted for regular addresses

1

Coin version accepted for Pay To Script Hash Addresses (BIP 16), or 0x00 if disabled

1

User PIN length (from 0x04 up to 0x20)

1

User PIN

var

Secondary PIN length (from 0x00 up to 0x04)

1

Secondary PIN

var

BIP32 Seed size (0x00 to generate a new 64 bytes seed, size between 32 and 64 to restore a seed backup)

1

BIP32 Seed if restoring a seed backup

variable

3DES-2 key wrapping key length for developer mode (0x00 to generate a new key, 0x10 to set up a backup)

1

3DES-2 key wrapping key for developer mode

null or 16

Input data (Point Of Sale setup)

Description

Length

Bitflag of supported operation modes

0x01 : wallet mode

0x02 : relaxed wallet mode

0x04 : server mode

0x08 : developer mode

1

Bitflag of features

0x01 : use uncompressed public keys in addresses (otherwise compress them)

0x02 : enable RFC 6979 deterministic signatures (otherwise use a random K)

0x04 : authorize all signature hashtypes (otherwise only authorize SIGHASH_ALL)

0x08 : skip second factor if consuming only P2SH inputs in a transaction

1

Coin version accepted for regular addresses

1

Coin version accepted for Pay To Script Hash Addresses (BIP 16), or 0x00 if disabled

1

User PIN length (from 0x04 up to 0x20)

1

User PIN

var

Secondary PIN length (from 0x00 up to 0x04)

1

Secondary PIN

var

BIP32 Seed size (0x00 to generate a new 64 bytes seed, 64 to restore a seed backup)

1

BIP32 Seed if restoring a seed backup

variable

0x00 or 0x10 if restoring a seed backup

1

3DES-2 seed backup wrapping key wrapping key if restoring a seed backup

null or 16

Input data (forward setup)

Description

Length

Bitflag of supported operation modes

0x01 : wallet mode

0x02 : relaxed wallet mode

1

Bitflag of features

0x01 : use uncompressed public keys in addresses (otherwise compress them)

0x02 : enable RFC 6979 deterministic signatures (otherwise use a random K)

0x04 : authorize all signature hashtypes (otherwise only authorize SIGHASH_ALL)

0x08 : skip second factor if consuming only P2SH inputs in a transaction

1

Coin version accepted for regular addresses

1

Coin version accepted for Pay To Script Hash Addresses (BIP 16), or 0x00 if disabled

1

User public key length

1

User public key

var

Password blob

40

BIP32 Seed size (0x00 to generate a new seed)

1

3DES-2 key wrapping key length for developer mode (0x00 to generate a new key)

1

The password blob is generated as follows :

  • An ECDH key exchange is performed on the user side using a newly generated keypair on the Bitcoin curve and the dongle Attestation public key - a 32 bytes secret is obtained, split into two 16 bytes components S1 and S2

  • S1 and S2 are XORed to produce a 16 bytes 3DES-2 session key

  • The following data is encrypted using 3DES CBC and the generated session key, and sent as password blob

Description

Length

User PIN length (from 0x04 up to 0x20)

1

User PIN (padded with random)

32

Secondary PIN length (from 0x00 up to 0x04)

1

Secondary PIN (padded with random)

4

Random data used as a XOR One Time Pad to mask the seed

64

CRC-16 of the previous data

2

Additional description of setup parameters

When enabled, RFC 6979 deterministic signatures will be used for all operations in wallet, relaxed wallet and server modes. RFC 6979 deterministic signatures are always available in developer mode.

Note
 Using deterministic signatures will make the signing process slower and could possibly create a larger side channel attack surface due to the way private keys are handled during the computation of the random value. We suggest to only enable this mode if you don’t trust the chip hardware Random Number Generator or are sure of understanding the risks.

The following sample Coin versions are defined for regular addresses

Network

Version (dec)

Bitcoin (main network)

0

Bitcoin (test network)

111

Litecoin (main network)

48

Litecoin (test network)

111

Dogecoin (main network)

30

Dogecoin (test network)

113

The following sample Coin version are defined for Pay To Script Hash addresses

Network

Version (dec)

Bitcoin (main network)

5

Bitcoin (test network)

196

Litecoin (main network)

5

Litecoin (test network)

196

Dogecoin (main network)

22

Dogecoin (test network)

196

If generating a new seed, the dongle generates a 64 bytes random number from its hardware Random Number Generator

A keymap encoding is a set of Keyboard HID Usage IDs mapping the keyboard layout of the computer on which the user validation is performed. It can be updated later using the SET KEYBOARD CONFIGURATION command.

Keymap encoding is coded as follows

Description

Length

ALT-GR usage keymap

12

Shift usage keymap

12

HID page table for ASCII codes from 0x20 to 0x7e

95

ALT-GR & Shift usage keymaps are coded as a set of flags indicating if the ALT-GR / Shift key should be pushed for the given mapping. First byte codes shift flags from keycode 0x20 (LSB) to 0x27 (MSB) and so on.

The default QWERTY Keymap Encoding is

00 00 00 00 00 00 00 00 00 00 00 00
76 0f 00 d4 ff ff ff c7 00 00 00 78
2c 1e 34 20 21 22 24 34 26 27
25 2e 36 2d 37 38 27 1e 1f 20
21 22 23 24 25 26 33 33 36 2e
37 38 1f 04 05 06 07 08 09 0a
0b 0c 0d 0e 0f 10 11 12 13 14
15 16 17 18 19 1a 1b 1c 1d 2f
31 30 23 2d 35 04 05 06 07 08
09 0a 0b 0c 0d 0e 0f 10 11 12
13 14 15 16 17 18 19 1a 1b 1c
1d 2f 31 30 35

Output data (if developer mode is supported)

Description

Length

Seed return flag

0x00 : seed is not typed to the user

0x01 : seed typed to the user

1

3DES-2 trusted input key

16

3DES-2 key wrapping key for developer mode

16

Output data (if developer mode is not supported)

Description

Length

Seed return flag

0x00 : seed is not typed to the user

0x01 : seed typed to the user

1

Output data (if using forward setup)

Description

Length

Seed return flag

0x00 : seed is not typed to the user

1

Seed XORed by the provided One Time Pad

64

Availability

This function is only available before the dongle is set up (either when received or following a dongle reset)

19.2. SET USER KEYCARD

19.2.1. Description

This command is used to replace the keyboard second factor by a printed keycard for regular (non relaxed) transactions.

The keycard associates each ASCII character between 0x30 and 0x7a (included) to an hexadecimal digit, obtained by encrypting 00..50 by the 3DES-2 keycard seed key using CBC encryption, and considering each digit as an exclusive OR of both nibbles of each element

When using the keycard second factor, the user needs to provide as authentication code random A characters of the destination address (up to 10)

This command allows the user to set a new keycard, similar to [Keycard]. This keycard will replace the system keycard if a system keycard was defined, until the dongle is reset.

If no previous keycard was set, this command is confirmed by the standard keyboard second factor. After issuing it, the user needs to confirm it using the unique PIN displayed by the second factor. Otherwise it is confirmed by a 4 bytes challenge with the previous keycard. The dongle must be power cycled if the challenge is not correct.

Note
 This command is not supported by devices offering a screen and buttons

19.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

10

01 : set keycard

02 : confirm keycard

00

11

var

Input data (set keycard)

Description

Length

Number of random address characters to provide

1

Keycard seed

16

Input data (confirm keycard)

Description

Length

Confirmation PIN or challenge

4

Output data (set keycard)

Description

Length

Confirmation mode

01 : keyboard second factor

02 : previous keycard challenge

01

If a previous keycard was set, challenge to match

04

Output data (confirm keycard)

None

Availability

This function is always available following dongle setup, and is protected by the user PIN.

19.3. SETUP SECURE SCREEN

19.3.1. Description

This command is used to replace a printed keycard second factor by a transaction summary displayed on a remote screen. A printed keycard must be set up before issuing this command.

The pairing process is performed as follows :

  • An ECDH key exchange is performed on the remote screen side side using a newly generated keypair on the Bitcoin curve and the dongle Attestation public key - a 32 bytes secret is obtained, split into two 16 bytes components S1 and S2

  • S1 and S2 are XORed to produce a 16 bytes 3DES-2 session key

  • The remote screen public key is sent to the dongle, which generates a cleartext random 8 bytes nonce, a 4 bytes challenge on the printed keycard and a random 16 bytes 3DES-2 pairing key, concatenated and encrypted using 3DES CBC and the generated session key

  • This message is decrypted on the remote screen side and the user is prompted for the printed card challenge, which is returned concatenated with the nonce, encrypted using 3DES CBC and the generated session key

  • The pairing process is completed on the dongle side if the challenge is correct, otherwise the dongle must be power cycled.

Note
 This command is not supported by devices offering a screen and buttons managed by the secure part of the device

19.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

12

01 : initiate pairing

02 : confirm pairing

00

var

00

Input data (initiate pairing)

Description

Length

Remote screen uncompressed public key

65

Input data (confirm pairing)

Description

Length

Encrypted nonce and challenge response + padding

16

Output data (initiate pairing)

Description

Length

Pairing blob : 8 bytes random nonce and (4 bytes keycard challenge + 16 bytes pairing key) encrypted by the session key

32

Output data (confirm keycard)

None

Availability

This function is always available following dongle setup, and is protected by the user PIN.

19.4. SET ALTERNATE COIN VERSIONS

19.4.1. Description

This command allows you to change the current coin version & P2SH version for the current session, until the dongle is reset.

It can be used to support several coin types in the derivation scheme using the same seed

19.4.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

14

00

00

02

00

Input data

Description

Length

Coin version accepted for regular addresses

1

Coin version accepted for Pay To Script Hash Addresses (BIP 16), or 0x00 if disabled

1

Output data

None

Availability

This function is always available following dongle setup, and is protected by the user PIN.

19.5. VERIFY PIN

19.5.1. Description

This command is used to unlock the dongle using the PIN provided during setup.

If forward setup mode was used, the seed will be typed to the user on the first PIN entry and signature operations are enabled if a keymap was set. Otherwise the command will be denied.

The dongle must be physically reset after each invalid PIN to issue a new command.

After 3 invalid PIN submitted in a row, the dongle data is erased and it must be setup again.

If the secondary PIN is entered instead of the user PIN, a random seed generated when the dongle is setup is used.

If P1 is set to 0x80, the dongle returns the number of remaining attempts. Arbitrary data must still be sent (f.e. 1 byte)

Note
 Devices offering a screen and buttons will override the PIN parameters to let the user enter it directly on device. Dummy values should be used from the caller.

19.5.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

22

00 : verify PIN

80 : get number of remaining attempts

00

var

00

Input data

Description

Length

PIN

var

Output data

Description

Length

PIN validation flags

0x01 : dongle was initialized in forward setup mode and needs to be power cycled to read the seed

1

Availability

This function is always available following dongle setup.

Specific Status Words

SW

Description

63Cx

Invalid PIN, x remaining attempts

19.6. GET OPERATION MODE

19.6.1. Description

This command returns the current operation mode used by the dongle

The forward setup mask is present if a forward setup mode was performed and the seed has not been redeemed by the end user yet.

19.6.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

24

00 : query the dongle operation mode

01 : query the second factor currently used

00

00

01

Input data

None

Output data (dongle operation mode)

Description

Length

Operation Mode

0x01 : standard wallet

0x02 : relaxed wallet

0x04 : server

0x08 : developer

0x80 : mask added if forward setup mode was used and the seed has not been redeemed yet

1

Output data (second factor in use)

Description

Length

Operation Mode

0x11 : original second factor (keyboard validation method)

0x12 : secondary second factor (security card)

0x13 : secondary second factory (security card and secure screen)

1

Availability

This function is always available following dongle setup.

19.7. SET OPERATION MODE

19.7.1. Description

This command sets the operation mode that will be used by the dongle after the next power up.

The dongle must be physically reset following this command if switching to a different mode than the current mode.

If a keycard or a secure screen have been provisioned, they can be enabled with this command. The alternate second factor is only enabled until the dongle is power cycled.

If the requested mode has been disabled on setup, an error will be returned.

19.7.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

26

00 : do not enable the alternate second factor (only valid if switching to standard operation mode)

01 : enable the alternate second factor until the dongle is power cycled (only valid if switching to standard operation mode)

02 : enable the alternate second factor permanently, until the seed is erased (only valid if switching to standard operation mode)

00

01

00

Input data

Description

Length

Operation Mode

0x01 : standard wallet

0x02 : relaxed wallet

0x04 : server

0x08 : developer

1

Output data

None

Availability

This function is always available following dongle setup, and is protected by the user PIN.

19.8. SET KEYBOARD CONFIGURATION

19.8.1. Description

This command sets or modifies the keymap and typing behaviour following dongle setup.

The keymap is encoded as in [KeymapEncoding]

Note
 This command is not supported by devices offering a screen and buttons

19.8.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

28

00 : set keymap

01 : set typing behaviour

00

var

00

Input data (set keymap)

Description

Length

ALT-GR usage keymap

12

Shift usage keymap

12

HID page table for ASCII codes from 0x20 to 0x7e

95

Input data (set typing behaviour)

Description

Length

Unit delay before starting to type (in CPU cycles, big endian)

4

Number of unit delay to wait before starting to type (big endian)

4

Unit delay between each key (in CPU cycles, big endian)

4

Number of unit delay to wait between each key (big endian)

4

Output data

None

Availability

This function is always available following dongle setup, and is protected by the user PIN if not operating in forward setup mode.

20. Wallet usage APDUs

20.1. GET WALLET PUBLIC KEY

20.1.1. Description

This command returns the public key and Base58 encoded address for the given BIP 32 path.

20.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

40

00

00

variable

variable

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

Output data

Description

Length

Public Key length

1

Uncompressed Public Key

var

Base58 bitcoin address length

1

Base58 encoded bitcoin address

var

BIP32 Chain code

32

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and server operation modes, and is protected by the user PIN.

20.2. GET TRUSTED INPUT

20.2.1. Description

This command is used to extract a Trusted Input (encrypted transaction hash, output index, output amount) from a transaction.

The transaction data to be provided should be encoded using bitcoin standard raw transaction encoding. Scripts can be sent over several APDUs. Other individual transaction elements split over different APDUs will be rejected. 64 bits varints are rejected.

20.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

42

00 : first transaction data block

80 : subsequent transaction data block

00

var

var

Input data (first block)

Description

Length

Input index to lookup (big endian)

4

Transaction data

var

Input data (next block)

Description

Length

Transaction data

var

Output data (non last block)

None

Output data (last block)

Description

Length

Trusted Input

56

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and server operation modes.

20.3. UNTRUSTED HASH TRANSACTION INPUT START

20.3.1. Description

This command is used to compose an opaque SHA-256 hash for a new transaction.

This transaction can be verified by the user and using transaction rules according to the current dongle operation mode.

If a new transaction is started, a VERIFY PIN command shall have been issued previously to unlock the dongle at least once following the dongle power up

The transaction data to be provided should be encoded using bitcoin standard raw transaction encoded as follows :

  • A 1 byte flag is added before each input in the transaction - if the input is passed as a Trusted Input, this flag is set to 0x01 - otherwise, it is set to 0x00. Non Trusted Inputs can be used in relaxed mode for inputs that are not signed, or for all P2SH inputs when the dongle has been setup to skip the second factor when dealing with P2SH inputs.

  • When using a Trusted Input, each input outpoint is replaced by the Trusted Input length (1 byte) and the Trusted Input data

  • The input scripts shall be prepared by the host for the transaction signing process as per bitcoin rules : the current input script being signed shall be the previous output script (or the redeeming script when consuming a P2SH output), and other input script shall be null.

  • The encoded transaction data shall be provided up to (and not including) the number of outputs.

  • Scripts can be sent over several APDUs. Other individual transaction elements split over different APDUs will be rejected. 64 bits varints are rejected.

20.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

44

00 : first transaction data block

80 : subsequent transaction data block

00 : start signing a new transaction

80 : continue signing another input of the current transaction

var

var

Input data

Description

Length

Transaction data

var

Output data

None

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and server operation modes, and is protected by the user PIN when starting to sign a new transaction (P1 and P2 set to 0x00)

20.4. UNTRUSTED HASH TRANSACTION INPUT FINALIZE

20.4.1. Description

This command is used to compose an opaque SHA-256 hash for the transaction outputs

This command is rejected if all inputs advertised at the beginning of the transaction have not been processed first.

The generated script will be the standard script coded as below given the address for a non script address

OP_DUP OP_HASH160 [pubKeyHash] OP_EQUALVERIFY OP_CHECKSIG

For a P2SH script address the generated script will be

OP_HASH160 [script hash] OP_EQUAL

The output amount, fees and change will be validated by the user in wallet or relaxed wallet modes.

A maximum 80 bytes OP_RETURN output script payload can be provided - it will be added to the transaction with a null amount

The generated transaction output data contains in pre-serialized form the number of outputs (target & optionally change) and each output data

If a keycard seed has been provided, and the wallet is operating in standard mode with the alternate second factor activated, an alternate second factor validation scheme is used, see [Keycard]

After 30 invalid second factor challenges submitted in a row, the dongle data is erased and it must be setup again.

Note
 On a device offering a screen and buttons, the confirmation will be prompted immediately and returned with code 0x00 (no confirmation requested) to the caller

20.4.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

46

01 : output address provided as version byte + binary hash160

02 : output address provided as base58 string

00

var

var

Input data

Description

Length

Length of the Output Address

1

Output Address (base58 or hash160)

var

Amount (big endian)

8

Fees (big endian)

8

Number of BIP 32 derivations to perform (max 10)

1

First derivation index for the internal change address (big endian)

4

…

4

Last derivation index for the internal change address (big endian)

4

Optional OP_RETURN output payload length

1

Optional OP_RETURN output payload

var

Output data (if no keycard seed is set)

Description

Length

Generated transaction output data length

1

Generated transaction output data

var

Transaction user validation flag

0x00 : no user validation requested

0x01 : user validation requested with keyboard confirmation

1

Output data (if keycard seed is set and no secure screen is paired)

Description

Length

Generated transaction output data length

1

Generated transaction output data

var

Transaction user validation flag

0x02 : user validation requested with keycard

1

Indexes of variable positions in the address to check

var

Output data (if keycard seed is set and a secure screen is paired)

Description

Length

Generated transaction output data length

1

Generated transaction output data

var

Transaction user validation flag

0x03 : user validation requested with secure screen or keycard

1

Number of variable positions in the address to check

1

Indexes of variable positions in the address to check

var

Second factor data 3DES-CBC encrypted by the pairing key

var

The second factor data is coded as follows

Description

Length

Unique PIN

4

Output amount (satoshis, big endian)

8

Fees (satoshis, big endian)

8

Change (satoshis, big endian)

8

Output address length

1

Output address

var

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and server operation modes.

20.5. UNTRUSTED HASH SIGN

20.5.1. Description

This command is used to sign a given secure hash using a private key (after re-hashing it following the standard Bitcoin signing process) to finalize a transaction input signing process.

This command will be rejected if the transaction signing state is not consistent or if a user validation is required and the provided user validation code is not correct.

20.5.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

48

00

00

var

var

Input data

Description

Length

Number of BIP 32 derivations to perform (max 10)

1

First derivation index for the private key to use (big endian)

4

…

4

Last derivation index for the private key to use (big endian)

4

User validation code length (or 0x00)

1

User validation code

var

Lock Time (big endian)

4

SigHashType

1

Output data

Description

Length

Signed hash, as ASN-1 encoded R & S components. Mask first byte with 0xFE

var

SigHashType

1

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and server operation modes.

20.6. UNTRUSTED HASH TRANSACTION INPUT FINALIZE FULL

20.6.1. Description

This command is used to compose an opaque SHA-256 hash for the transaction outputs

This command is rejected if all inputs advertised at the beginning of the transaction have not been processed first.

Output data can be split arbitrarily.

Note
 On a device offering a screen and buttons, the confirmation will be prompted immediately and returned with code 0x00 (no confirmation requested) to the caller

20.6.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

4A

00 : more input data to be sent

80 : last input data block to be sent

00

var

var

Input data (first block)

Description

Length

Start of output data, containing the number of outputs encoded as a Bitcoin varint

var

Input data (optional next blocks)

Description

Length

Output data continued

var

Output data (not last block)

None

Output data (last block)

Description

Length

Transaction user validation flag

0x00 : no user validation requested

0x01 : user validation requested

1

Availability

This function is available following dongle setup in standard wallet mode when the dongle has been setup to skip the second factor when dealing with P2SH inputs and the current transaction is consuming P2SH inputs, or always available following dongle setup in relaxed wallet and server operation modes.

20.7. SIGN MESSAGE

20.7.1. Description

This command is used to sign a maximum 140 bytes long text message using a private key. The message must be ASCII printable (each byte of the message must be between 0x20 and 0x7e, both included)

The message is provided to the dongle, which types it along with a single usage transaction PIN when it’s power cycled.

The transaction PIN is then sent back to this command to retrieve the message signature

The signature is performed as follows :

  • The data to sign is the magic "\x18Bitcoin Signed Message:\n" - followed by the length of the message to sign on 1 byte (if requested) followed by the binary content of the message

  • The signature is performed on a double SHA-256 hash of the data to sign using the selected private key

The signature is returned using the standard ASN-1 encoding. To convert it to the proprietary Bitcoin-QT format, the host has to :

  • Get the parity of the first byte (sequence) : P

  • Add 27 to P if the public key is not compressed, otherwise add 31 to P

  • Return the Base64 encoded version of P || r || s

If the low end word of one component of the BIP 32 derivation path includes 0xB11D or 0xB11E the message is immediately signed without confirmation (typically used for BitID). The dongle must be powercycled after signing with a derivation path containing 0xB11D.

Note
 On a device offering a screen and buttons, the confirmation will be prompted immediately and returned with code 0x00 (no confirmation requested) to the caller. Limitations regarding the message content and length can be different.

20.7.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

4E

00 : prepare message

80 : sign message

00

var

var

Input data in prepare mode

Description

Length

Number of BIP 32 derivations to perform (max 10)

1

First derivation index of the private key to use (big endian)

4

…

4

Last derivation index of the private key to use (big endian)

4

Message length (max 140)

1

Message

var

Input data in sign mode

Description

Length

User validation code length (or 00 in server mode)

1

User validation code

var

Output data in prepare mode

Description

Length

Transaction user validation flag

0x00 : no user validation requested

0x01 : user validation requested

1

Output data in sign mode

Description

Length

ASN-1 encoded message signature with Y parity indicated in the first (sequence) byte

variable

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and server operation modes and is protected by the user PIN when preparing a message to sign (P1 set to 0x00)

21. Personal BIP 70 Certificates APDUs

21.1. STORE TRUST ROOT BIP 70

21.1.1. Description

This command is used to store a user controlled trust root private key in a slot (3 slots are defined). It must be executed in a secure environment.

A keyboard second factor validation is required to proceed.

Note
 On a device offering a screen and buttons, the confirmation will be prompted immediately.

21.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

30

01 : prepare trust root

80 : confirm trust root

00

var

var

Input data (prepare trust root)

Description

Length

Trust root slot (0 to 2)

1

Trust root identity length

1

Trust root identity (max 20 bytes)

var

Private key value

32

Input data (confirm trust root)

Description

Length

User validation code

var

Output data (prepare trust root)

None

Output data (confirm trust root)

Description

Length

Self signed certificate for this identity and trust root

var

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and is protected by the user PIN

21.2. CREATE CERTIFICATE BIP 70

This command is used to create a new BIP 70 certificate associating an identity to a BIP 32 key path for the current seed and signed by the given Trusted Root. All children of this path can be certified by this certificate.

The dongle returns a private part, wrapped for this dongle, containing the certificate private key, the BIP 32 path and the checksum of the public key at this root path, a certificate signed by the given Trust Root, and a checksum of the certificate that can be passed to the client through a second channel for validation.

21.2.1. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

32

00 : generate the certificate

80 : retrieve the second part of the certificate

00

var

var

Input data (first part)

Description

Length

Trust root slot (0 to 2)

1

Number of BIP 32 derivations to perform (max 9)

1

First derivation index (big endian)

4

…

4

Last derivation index (big endian)

4

Subject Common Name length

1

Subject Common Name (max 20 bytes)

var

Validity start as UTC time

13

Validity end as UTC time

13

Input data (second part)

None

Output data (first part)

Description

Length

Certificate private part length

1

Certificate private part blob

var

Certificate public part checksum length

1

Certificate public part checksum

var

DER encoded certificate (first part)

var

Output data (second part)

Description

Length

DER encoded certificate (second part)

var

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and is protected by the user PIN

21.3. CREATE PAYMENT REQUEST BIP 70

This command is used to create a new signed PaymentRequest with the provided certificate, validating that the address belongs to the user by checking that the provided BIP 32 derivation path is a child of the BIP 32 derivation path associated to the certificate.

The PaymentRequest is prepared by the host and passed to the dongle for validation and signature. Elements serialized as Protocol Buffers wire types other than 2 shall be provided in a single APDU. The tag and length of elements serialized as Protocol Buffer wire type 2 shall be provided in a single APDU. The output script and pki_type shall be provided as a single APDU.

The following elements of the PaymentRequest are validated by the dongle :

  • PaymentRequest.pki_type is set to x509+sha256

  • PaymentDetails.outputs has a single element

  • Output.script contains a simple transfer to the given derived address

After validating the PaymentRequest, the dongle returns its signature.

21.3.1. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

34

00 : initialization

80 : PaymentRequest chunk

00 : more PaymentRequest chunks expected

80 : last PaymentRequest chunk

var

var

Input data (initialization)

Description

Length

Certificate private part length

1

Certificate private part

var

Number of BIP 32 derivations to perform (max 10)

1

First derivation index (big endian)

4

…

4

Last derivation index (big endian)

4

Input data (next payment request chunk)

Description

Length

Serialized PaymentRequest chunk

var

Output data (initialization)

Description

Length

Output script length

1

Output script

var

Output data (last PaymentRequest chunk)

Description

Length

PaymentRequest signature

var

Output data (other)

None

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and is protected by the user PIN

21.4. PROCESS CERTIFICATE BIP 70

This command is used to approve the future use of an external BIP 70 Certificate by a dongle.

After submitting the request, the certificate checksum is typed by the second factor. If validated and confirmed by the user, the encoded certificate valid for this dongle is returned.

Note
 On a device offering a screen and buttons, the confirmation will be prompted immediately.

21.4.1. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

36

00 : prepare certificate

80 : confirm certificate

00 : when preparing, first certificate block

01 : when preparing, more certificate blocks expected

80 : when preparing, last certificate block

var

var

Input data (prepare certificate, first block)

Description

Length

Trust root slot (0 to 2)

1

BIP 70 Certificate part

var

Input data (prepare certificate, next block or last block)

Description

Length

BIP 70 Certificate part

var

Input data (confirm certificate)

Description

Length

User validation code

var

Output data (prepare certificate)

None

Output data (confirm certificate)

Description

Length

Encoded BIP 70 Certificate for this dongle

var

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and is protected by the user PIN

21.5. PARSE PAYMENT REQUEST BIP 70

This command is used to approve the future use of an external BIP 70 Payment Request by a dongle.

The serialzied PaymentRequest is passed to the dongle for validation. Elements serialized as Protocol Buffers wire types other than 2 shall be provided in a single APDU. The tag and length of elements serialized as Protocol Buffer wire type 2 shall be provided in a single APDU.

If the PaymentRequest is successfully validated, an encoded PaymentRequest valid for this dongle is returned

21.5.1. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

38

00 : initialization

80 : PaymentRequest chunk

00 : more PaymentRequest chunks expected

80 : last PaymentRequest chunk

var

var

Input data (first payment request chunk)

Description

Length

Encoded certificate length

1

Encoded certificate

var

Input data (next payment request chunk)

Description

Length

Serialized PaymentRequest chunk

var

Output data (last PaymentRequest chunk)

Description

Length

Encoded PaymentRequest for this dongle

var

Output data (other)

None

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet and is protected by the user PIN

21.6. UNTRUSTED HASH TRANSACTION INPUT FINALIZE BIP 70

21.6.1. Description

This command is used to compose an opaque SHA-256 hash for the transaction outputs

This command is rejected if all inputs advertised at the beginning of the transaction have not been processed first.

The output address and amount are provided by a previously encoded PaymentRequest

21.6.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

3A

00

00

var

var

Input data

Description

Length

Length of encoded PaymentRequest

1

Encoded PaymentRequest

var

Fees (big endian)

8

Number of BIP 32 derivations to perform (max 10)

1

First derivation index for the internal change address (big endian)

4

…

4

Last derivation index for the internal change address (big endian)

4

Output data

Description

Length

Availability

This function is always available following dongle setup in standard wallet, relaxed wallet modes.

22. Server mode APDUs

22.1. GET TRANSACTION LIMIT

22.1.1. Description

This command returns the current cumulative amount limit and the number of transactions remaining

Warning
 This function is not supported in this version

22.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

A0

00

00

00

0C

Input data

None

Output data

Description

Length

Remaining cumulative amount (big endian)

8

Remaining number of transactions

4

Availability

This function is always available following dongle setup in server operation modes.

22.2. SET TRANSACTION LIMIT

22.2.1. Description

This command sets the current cumulative amount limit and the number of transactions remaining.

This command is protected by the HOTP server key. If the OTP is correct, the command is executed, the transaction limit is updated immediately and the OTP sequence counter is increased.

Warning
 This function is not supported in this version

22.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

A2

00

00

10

var

Input data

Description

Length

8 digits HOTP code

8

Cumulative amount (big endian)

8

Number of transactions after power up

4

Output data

None

Availability

This function is always available following dongle setup in server operation modes.

23. Developer mode APDUs

23.1. IMPORT PRIVATE KEY

23.1.1. Description

This command imports a regular private key, a BIP32 private key or a BIP32 seed and returns an encrypted version of the private key that this dongle can use for future operations.

23.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

B0

Import method

0x01 : Base58 encoded private key or BIP32 private key

0x02 : BIP32 seed

00

var

var

Input data

Description

Length

Base58 private key or seed

var

Output data

Description

Length

Encoded private key

var

Availability

This function is always available following dongle setup in developer operation mode.

23.2. GET PUBLIC KEY

23.2.1. Description

This command returns the public key or the extended public key for an encoded private key

23.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

B2

00

00

var

var

Input data

Description

Length

Encoded private key length

1

Encoded private key

var

Output data (non HD key)

Description

Length

Flag : 0x01

1

Public key length

1

Public key

var

Output data (HD key)

Description

Length

Flag : 0x02

1

Public key length

1

Public key

var

Chain code

32

Depth

1

Parent fingerprint

4

Child number (big endian)

4

Availability

This function is always available following dongle setup in developer operation mode, and is protected by the user PIN.

23.3. DERIVE BIP32 KEY

23.3.1. Description

This command derives a BIP32 key to return a child key.

This command returns an error if operating on a non BIP32 key

Both hardened and non hardened derivation modes are supported.

23.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

B4

00

00

var

var

Input data

Description

Length

Encoded private key length

1

Encoded private key

var

Child index (big endian)

4

Output data

Description

Length

Encoded private key

var

Availability

This function is always available following dongle setup in developer operation mode.

23.4. ECDSA SIGN/VERIFY IMMEDIATE

23.4.1. Description

This command is used to sign a given hash using an encoded private key or verify a given signature using a public key

23.4.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

B6

00 : sign

80 : verify

00 : sign with random K

80 : sign with deterministic K

var

var

Input data (sign mode)

Description

Length

Length of encoded private key

1

Encoded private key

var

Length of hash to sign (up to 32 bytes)

1

Hash to sign

var

Input data (verify mode)

Description

Length

Length of uncompressed public key

1

Uncompressed Public key

var

Length of hash to verify (up to 32 bytes)

1

Hash to verify  

var

Signature

var

Output data (sign mode)

Description

Length

Signed hash, as ASN-1 encoded R & S components. Mask first byte with 0xFE

var

Output data (verify mode)

None

Availability

This function is always available following dongle setup in developer operation mode, and is protected by the user PIN

24. Test and utility APDUs

24.1. GET RANDOM

24.1.1. Description

This command returns random bytes from the dongle hardware random number generator

24.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

C0

00

00

00

variable

Input data

None

Output data

Description

Length

Random bytes

variable

Availability

This function is always available.

24.2. GET DEVICE ATTESTATION

24.2.1. Description

This command returns a signature of the 6 bytes current firmware version concatenated to the given blob by the attestation key.

24.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

C2

00

00

08

variable

Input data

Description

Length

Blob to sign

8

Output data

Description

Length

Attestation key batch ID

04

Attestation key derivation index ID

04

Supported operation modes bitflag

01

Current operation mode

01

Firmware major version

02

Firmware minor version

01

Firmware patch version

01

Loader ID major version

01

Loader ID minor version

01

Signature of 8 previous bytes + blob

variable

Availability

This function is always available.

24.3. GET FIRMWARE VERSION

24.3.1. Description

This command returns the firmware version of the dongle and additional features supported

24.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

C4

00

00

00

07

Input data

None

Output data

Description

Length

Features flag

0x01 : public keys are compressed (otherwise not compressed)

0x02 : implementation running with screen + buttons handled by the Secure Element

0x04 : implementation running with screen + buttons handled externally

0x08 : NFC transport and payment extensions supported

0x10 : BLE transport and low power extensions supported

0x20 : implementation running on a Trusted Execution Environment

01

Architecture (only since Ledger Wallet, or RFU)

01

Firmware major version

01

Firmware minor version

01

Firmware patch version

01

Loader ID major version (if applicable)

01

Loader ID minor version (if applicable)

01

Availability

This function is always available.

24.4. COMPOSE M OF N ADDRESS

24.4.1. Description

This command is used to create and check on the fly a P2SH payment address to an M of N transaction, according to BIP 16 and BIP 11.

Each public key address is prompted to the user and validated by entering a PIN code as per the second factor mechanism.

After all public key addresses have been provided, the final address is typed to the user using the second factor mechanism.

Public keys can be provided in compressed or uncompressed format.

Warning
 This function is not supported in this version

24.4.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

C6

00 : start composing a new address

80 : continue composing an address with a new public key

00

variable

variable

Input data (for a new address)

Description

Length

M (number of signatures to provide to redeem the transaction, must be smaller than or equal to N)

01

N (total number of public keys provided, must be smaller than or equal to 3)

01

Public key

var

Input data (to keep on submitting a new key)

Description

Length

Authorization length

1

Authorization

var

Optional Public key, ignored for the last one

var

Output data

Description

Length

User validation flag

0x01 : user validation requested

1

Availability

This function is always available following dongle setup (but is not usable in server mode)

24.5. GET POINT OF SALE SEED

24.5.1. Description

This command is used to retrieve the seed backup if the dongle was set up in Point Of Sale mode.

The seed backup is split into 2 components :

  • A seed 3DES encryption key, randomly generated by the dongle

  • The encrypted seed

It is recommended to retrieve each seed component on a different host.

The dongle must be powercycled after processing this command.

24.5.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

CA

01 : request seed encryption key

02 : request encrypted seed

00

variable

variable

Input data

None

Output data (for seed encryption key)

Description

Length

Seed encryption key

16

Output data (for encrypted seed)

Description

Length

Encrypted seed

64

Availability

This function is available after setup in Point Of Sale mode and is disabled after the encrypted seed is retrieved once

25. Vendor management APDUs

These APDUs are used for factory setup and firmware updates.

25.1. FACTORY INITIALIZE KEYS

25.1.1. Description

This command is used to derive the factory update, attestation storage, and optional BIP 70 initial Trust Root storage from the shared rom key before issuance.

25.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

D0

20

00

00

28 or 38

00

Input data

Description

Length

Firmware update ID

08

Attestation storage key diversifier

10

Firmware update key diversifier

10

BIP 70 Trust Root key diversifier

10

Output data

None

Availability

This function is only available pre issuance

25.2. FACTORY INITIALIZE ATTESTATION

25.2.1. Description

This command sets up the attestation private key used to authenticate the device.

The dongle switches to post-issuance mode once this APDU is received and handled successfully.

25.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

D0

22

00

00

2B

00

Input data

Description

Length

Attestation key batch ID

04

Attestation key derivation index ID

04

Wrapped attestation private key

35

Output data

None

Availability

This function is only available pre issuance

25.3. GET FIRMWARE UPDATE ID

25.3.1. Description

This command returns the firmware update ID of this dongle.

25.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

D0

24

00

00

00

08

Input data

None

Output data

Description

Length

Firmware update ID

08

Availability

This function is only available before the dongle is set up (either when received or following a dongle reset)

25.4. FACTORY INITIALIZE KEYCARD SEED

25.4.1. Description

This command is used to replace the keyboard second factor by a printed keycard for regular (non relaxed) transactions

The keycard associates each ASCII character between 0x30 and 0x7a (included) to an hexadecimal digit, obtained by encrypting 00..50 by the 3DES-2 keycard seed key using CBC encryption, and considering each digit as an exclusive OR of both nibbles of each element

When using the keycard second factor, the user needs to provide as authentication code random A characters of the destination address (up to 10)

25.4.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

D0

26

00

00

11

00

Input data

Description

Length

Number of random address characters to provide

1

Keycard seed

16

Output data

None

Availability

This function is only available pre issuance

25.5. FACTORY INITIALIZE BIP 70 TRUST ROOT

25.5.1. Description

This command sets up an initial BIP 70 Trust Root

25.5.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

D0

28

00

00

var

00

Input data

Description

Length

Wrapped (slot index + Trust root identity length + Trust root identity (max 20 bytes) + BIP 70 Trust Root private key)

var

Output data

None

Availability

This function is only available pre issuance

25.6. FIRMWARE UPDATE

25.6.1. Description

This command is used to update the dongle firmware.

The dongle must not been set up to issue this command - if the dongle is set up, first wipe the user data by issuing the wrong user PIN 3 times.

Note
 Support of this APDU is device dependent.

25.6.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

D0

42

03 : start bootloader

06 : load bootloader

00

variable

00

Input data

Description

Length

Firmware blob

variable

Output data

None

Availability

This function is only available before the dongle is set up (either when received or following a dongle reset)

26. Transport protocol

26.1. General transport description

Ledger APDUs requests and responses are encapsulated using a flexible protocol allowing to fragment large payloads over different underlying transport mechanisms.

The common transport header is defined as follows :

Description

Length

Communication channel ID (big endian)

2

Command tag

1

Packet sequence index (big endian)

2

Payload

var

The Communication channel ID allows commands multiplexing over the same physical link. It is not used for the time being, and should be set to 0101 to avoid compatibility issues with implementations ignoring a leading 00 byte.

The Command tag describes the message content. Use TAG_APDU (0x05) for standard APDU payloads, or TAG_PING (0x02) for a simple link test.

The Packet sequence index describes the current sequence for fragmented payloads. The first fragment index is 0x00.

26.2. APDU Command payload encoding

APDU Command payloads are encoded as follows :

Description

Length

APDU length (big endian)

2

APDU CLA

1

APDU INS

1

APDU P1

1

APDU P2

1

APDU length

1

Optional APDU data

var

APDU payload is encoded according to the APDU case

Case Number

Lc

Le

Case description

1

0

0

No data in either direction - L is set to 00

2

0

!0

Input Data present, no Output Data - L is set to Lc

3

!0

0

Output Data present, no Input Data - L is set to Le

4

!0

!0

Both Input and Output Data are present - L is set to Lc

26.3. APDU Response payload encoding

APDU Response payloads are encoded as follows :

Description

Length

APDU response length (big endian)

2

APDU response data and Status Word

var

26.4. USB mapping

Messages are exchanged with the dongle over HID endpoints over interrupt transfers, with each chunk being 64 bytes long. The HID Report ID is ignored.

27. Status Words

The following standard Status Words are returned for all APDUs - some specific Status Words can be used for specific commands and are mentioned in the command description.

Status Words

SW

Description

6700

Incorrect length

6982

Security status not satisfied (Bitcoin dongle is locked or invalid access rights)

6A80

Invalid data

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (Internal error, please report)

9000

Normal ending of the command

28. Data structures

The format of the data structures is provided for interoperability and validation purposes. A typical user will not need to manipulate them directly.

28.1. Encoded private key in developer mode

An encoded private key is stored internally as follow. The private key component (S) and optional chain are triple DES encrypted by the developer mode wrapping key in CBC mode with a null IV (as S alone or S concatenated to the chain code)

Description

Length

Magic version (01)

1

Private key type

0x01 : standard private key

0x02 : BIP32 private key

1

Version

1

Private key component (S)

32

If BIP32, chain code

32

If BIP32, depth

1

If BIP32, parent fingerprint

4

If BIP32, child number (big endian)

4

28.2. Encoded trusted input

An encoded trusted input is stored internally as follow. The signature is the last block of a Triple DES CBC encryption of the previous data by the trusted input encryption key.

Description

Length

Magic version (32)

1

Flags

RFU

1

Nonce

2

Associated transaction hash

32

Index in associated transaction

4

Associated amount

8

Signature

8

28.3. Encoded private part of a BIP 70 Personal Certificate

An encoded private part of a BIP 70 Personal Certificate is stored internally as follow. The private key component is triple DES encrypted by the BIP 70 encryption key in CBC mode with a null IV. The signature is the last block of a Triple DES CBC encryption of the previous data by the BIP 70 signature key.

Description

Length

Magic version (03)

1

Flags

RFU

1

Encrypted certificate private key

32

Associated public key checksum

4

Number of BIP 32 derivations to perform (max 9)

1

First derivation index (big endian)

4

…

4

Last derivation index (big endian)

4

Nonce

var

Signature

8

28.4. Encoded BIP 70 Personal Certificate for dongle consumption

An encoded BIP 70 Personal Certificate for dongle consumption is stored internally as follow. The signature is the last block of a Triple DES CBC encryption of the previous data by the BIP 70 signature key.

Description

Length

Magic version (04)

1

Flags

RFU

1

Certificate public key

65

Subject Common Name length

1

Subject Common Name

var

Nonce

var

Signature

8

28.5. Encoded BIP 70 PaymentRequest for dongle consumption

An encoded BIP 70 PaymentRequest for dongle consumption is stored internally as follow. The signature is the last block of a Triple DES CBC encryption of the previous data by the BIP 70 signature key.

Description

Length

Magic version (05)

1

Flags

RFU

1

Amount

8

Output script length

1

Output script

var

Nonce

var

28.6. Specific data transport for firmware update or private key attestation storage

Data sent for firmware update or private key attestation storage is formatted as follows, encrypted by either the diversified firmware update key or the diversified attestation storage key

Description

Length

Data size without padding

01

3DES-CBC encrypted data with a null IV

variable

Padding

variable

CRC-16 of the cleartext data block

02

The target key is disabled after 10 invalid CRC-16 have been received in sequence.

After each invalid CRC-16, the dongle has to be power cycled before accepting another command.

29. Attestation keys

The following Attestation keys are used for production versions :

  • Batch ID 01, Derivation Index ID 01 (pre 1.4.11) : 04223314cdffec8740150afe46db3575fae840362b137316c0d222a071607d61b2fd40abb2652a7fea20e3bb3e64dc6d495d59823d143c53c4fe4059c5ff16e406

  • Batch ID 02, Derivation Index ID 01 (post 1.4.11) : 04c370d4013107a98dfef01d6db5bb3419deb9299535f0be47f05939a78b314a3c29b51fcaa9b3d46fa382c995456af50cd57fb017c0ce05e4a31864a79b8fbfd6

The following Attestation key is used for test versions :

04e69fd3c044865200e66f124b5ea237c918503931bee070edfcab79a00a25d6b5a09afbee902b4b763ecf1f9c25f82d6b0cf72bce3faf98523a1066948f1a395f