1. 1.0
-
Public release
2. About
This specification describes extensions to the general specification used by the Java Card implementation of Ledger Wallet, and differences between the Open Source version avaialble at https://github.com/LedgerHQ/ledger-javacard and specific versions implementing the Proprietary API interface described in com.ledger.wallet.ProprietaryAPI
3. Personalization APDUs
Since it might not be convenient to initialize a contactless applet on an airgapped computer an additional pairing system is defined.
When the applet instance is created, it is provisioned with a unique keypair and signature of its public key. This keypair will be used as an attestation key for ephemeral keys when establishing a symmetric key with the airgapped computer through an ECDH exchange.
After agreeing on a symmetric key, that key will be used to encrypt the keycard, the recovery seed or a seed generated by the applet.
3.1. Installation parameters
The following installation parameters are expected if you wish to use the personalization features
Description |
Length |
Attestation private key |
32 |
Attestation public key signature |
var |
Then the Attestation public key shall be set using the SET ATTESTATION PUBLIC KEY APDU following the instance creation
3.2. PERFORM AIRGAP KEY AGREEMENT
3.2.1. Description
This command is used to negociate a secret key with a remote host, supposedly disconnected. The 32 bytes negociated secret will be used to encrypt sensitive material with AES-256 CBC.
3.2.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
40 |
01 : Initiate pairing 02 : Confirm pairing |
00 |
var |
var |
Input data (for Initiate pairing)
Description |
Length |
Remote party uncompressed public key |
65 |
Input data (for Confirm pairing)
Description |
Length |
Secret key AES-256 CBC encrypted by the negociated secret |
32 |
Output data (for Initiate pairing)
Description |
Length |
Ephemeral uncompressed public key |
65 |
Ephemeral uncompressed public key DER signature by the attestation key |
var |
Output data (for Confirm pairing)
None
Availability
This function is only available before setup
3.3. SETUP AIRGAP
3.3.1. Description
This command is similar to the SETUP command, encoded for regular setup.
If a recovery seed is provided, it is decrypted by the previously negociated key.
If no recovery seed is provided, the output parameters are modified to include the encrypted application generated random seed.
3.3.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
42 |
00 |
00 |
var |
var |
Input data
See SETUP input data parameters for regular setup.
Output data (if developer mode is supported)
Description |
Length |
Seed return flag 0xF0 : encrypted seed available |
1 |
3DES-2 trusted input key |
16 |
3DES-2 key wrapping key for developer mode |
16 |
AES-256 CBC encrypted seed |
64 |
Output data (if developer mode is not supported)
Description |
Length |
Seed return flag 0xF0 : encrypted seed available |
1 |
AES-256 CBC encrypted seed |
64 |
Availability
This function is only available before setup
3.4. FACTORY INITIALIZE KEYCARD SEED AIRGAP
3.4.1. Description
This command is similar to the FACTORY INITIALIZE KEYCARD SEED command, with the seed content encrypted by the previously negociated key
3.4.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
44 |
00 |
00 |
11 |
00 |
Input data
Description |
Length |
Number of random address characters to provide |
1 |
Encrypted keycard seed |
16 |
Output data
None
Availability
This function is only available before setup
3.5. SET USER KEYCARD AIRGAP
3.5.1. Description
This command is similar to the SET USER KEYCARD command, with the seed content encrypted by the previously negociated key
3.5.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
46 |
01 : set keycard 02 : confirm keycard |
00 |
11 |
var |
Input data (set keycard)
Description |
Length |
Number of random address characters to provide |
1 |
Encrypted keycard seed |
16 |
Input data (confirm keycard)
Description |
Length |
Confirmation challenge |
4 |
Output data (set keycard)
Description |
Length |
Confirmation mode 02 : previous keycard challenge |
01 |
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.
3.6. SET ATTESTATION PUBLIC KEY
3.6.1. Description
This command is used during the personalization process to push the public key associated to the attestation private key sent in the installation parameters over a secure channel
3.6.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
48 |
00 |
00 |
41 |
var |
Input data
Description |
Length |
Attestation public key |
65 |
Output data
None
Availability
This function is only available before the dongle is setup
3.7. GET ATTESTATION
3.7.1. Description
This command is used to return the attestation public key and its signature
3.7.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
4A |
00 |
00 |
00 |
var |
Input data
None
Output data
Description |
Length |
Unique attestation public key |
65 |
Ledger attestation public key DER signature |
var |
Availability
This function is only available before the dongle is setup
4. Public key derivation APDUs
Additional APIs are defined to handle platforms which do not support full key agreement described in the Proprietary API allowing to obtain the X and Y components of a public key from its private key
4.1. GET HALF PUBLIC KEY
4.1.1. Description
This command returns the X component of a public key a signature to recover the Y component
4.1.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
20 |
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 |
Nonce to be signed |
32 |
X component of the public key |
32 |
DER encoded signature of the Nonce with the associated private key |
var |
Availability
This function is always available if no proprietary API is available following dongle setup in standard wallet, relaxed wallet and server operation modes, and is protected by the user PIN if not ready to sign.
4.2. PUT PUBLIC KEY CACHE
4.2.1. Description
This command stores a public key into the applet internal cache to use the regular application flow on platforms that cannot recover the Y component of a public key by themselves.
The validity of the public key is enforced by checking a random nonce signature before updating the cache.
4.2.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
22 |
00 |
00 |
variable |
00 |
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 |
Uncompressed public key |
64 |
Output data
None
Availability
This function is always available if no proprietary API is available following dongle setup in standard wallet, relaxed wallet and server operation modes
4.3. HAS PUBLIC KEY CACHE
4.3.1. Description
This command checks if a public key is present in the applet internal cache
4.3.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
24 |
00 |
00 |
variable |
01 |
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 |
Flag 01 : public key was found in cache |
1 |
Availability
This function is always available if no proprietary API is available following dongle setup in standard wallet, relaxed wallet and server operation modes
5. Information APDUs
5.1. GET JAVA CARD FEATURES
5.1.1. Description
This command returns information about specific Java Card features supported by this implementation
5.1.2. Coding
Command
CLA |
INS |
P1 |
P2 |
Lc |
Le |
F0 |
26 |
00 |
00 |
00 |
01 |
Input data
None
Output data
Description |
Length |
Flag 01 : a proprietary API implementation (as in ProprietaryApi.java interface implementation) is available |
1 |
Availability
This function is always available
6. Generic APDUs support
This chapter reviews the differences between the Generic APDUs described on https://ledgerhq.github.io/btchip-doc/bitcoin-technical.html and their implementation on the Java Card implementation
6.1. Lifecycle management APDUs
6.1.1. SETUP
Only regular setup and recovery are supported. The seed is displayed on the NDEF interface instead of being typed if the NDEF applet is installed
6.1.2. SET USER KEYCARD
This APDU is implemented as is
6.1.3. SETUP SECURE SCREEN
This APDU is not supported
6.1.4. SET ALTERNATE COIN VERSIONS
This APDU is not supported yet
6.1.5. VERIFY PIN
This APDU is implemented as is
6.1.6. GET OPERATION MODE
This APDU is implemented as is (but modes are not supported)
6.1.7. SET OPERATION MODE
This APDU is not supported yet
6.1.8. SET KEYBOARD CONFIGURATION
This APDU is not supported
6.2. Wallet usage APDUs
6.2.1. GET WALLET PUBLIC KEY
This APDU is implemented as is
6.2.2. GET TRUSTED INPUT
This APDU is implemented as is
6.2.3. UNTRUSTED HASH TRANSACTION INPUT START
This APDU is implemented as is
6.2.4. UNTRUSTED HASH TRANSACTION INPUT FINALIZE
This APDU is implemented as is (with a different second factor logic)
6.2.5. UNTRUSTED HASH SIGN
This APDU is implemented as is
6.2.6. UNTRUSTED HASH TRANSACTION INPUT FINALIZE FULL
This APDU is implemented as is (with a different second factor logic)
6.2.7. SIGN MESSAGE
This APDU is only supported on direct BitID signature paths (including SLIP 13)
6.3. Personal BIP 70 Certificates APDUs
6.3.1. STORE TRUST ROOT BIP 70
This APDU is not supported yet
6.3.2. CREATE CERTIFICATE BIP 70
This APDU is not supported yet
6.3.3. CREATE PAYMENT REQUEST BIP 70
This APDU is not supported yet
6.3.4. PROCESS CERTIFICATE BIP 70
This APDU is not supported yet
6.3.5. PARSE PAYMENT REQUEST BIP 70
This APDU is not supported yet
6.3.6. UNTRUSTED HASH TRANSACTION INPUT FINALIZE BIP 70
This APDU is not supported yet
6.4. Server mode APDUs
6.4.1. GET TRANSACTION LIMIT
This APDU is not supported
6.4.2. SET TRANSACTION LIMIT
This APDU is not supported
6.5. Developer mode APDUs
6.5.1. IMPORT PRIVATE KEY
This APDU is not supported yet
6.5.2. GET PUBLIC KEY
This APDU is not supported yet
6.5.3. DERIVE BIP32 KEY
This APDU is not supported yet
6.5.4. ECDSA SIGN/VERIFY IMMEDIATE
This APDU is not supported yet
6.6. Test and utility APDUs
6.6.1. GET RANDOM
This APDU is not supported yet
6.6.2. GET DEVICE ATTESTATION
This APDU is not supported
6.6.3. GET FIRMWARE ATTESTATION
This APDU is not supported
6.6.4. COMPOSE M OF N ADDRESS
This APDU is not supported
6.6.5. GET POINT OF SALE SEED
This APDU is not supported
6.7. Vendor management APDUs
6.7.1. FACTORY INITIALIZE KEYS
This APDU is not supported
6.7.2. FACTORY INITIALIZE ATTESTATION
This APDU is not supported
6.7.3. GET FIRMWARE UPDATE ID
This APDU is not supported
6.7.4. FACTORY INITIALIZE KEYCARD SEED
This APDU is implemented as is
6.7.5. FACTORY INITIALIZE BIP 70 TRUST ROOT
This APDU is not supported yet
6.7.6. FIRMWARE UPDATE
This APDU is not supported
7. Transport protocol
The Java Card application uses the standard ISO 7816 or 14443 transport protocols