1. 1.4.2 (Bitcoin 2013 release)

  • [enh] New security rules & operation modes

2. 1.4.1 (private release)

  • [enh] ECC operations speed-up

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

3. 1.4.0 (29c3 release)

  • Initial release

4. About

BTChip is a USB smartcard/dongle dedicated to secure bitcoin transactions. It performs all sensitive cryptographic operations related to a bitcoin transaction (key generation & signature) onboard, and helps protect against malware in an untrusted environment by controlling the signed data.

5. Operation modes

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

Two operation modes are defined, from the less restrictive to the more restrictive :

  • Fully trusted : This mode should be reserved to known trusted environments. Arbitrary data can be signed, and no control is performed over bitcoin transactions.

  • Moderately trusted : This mode should be reserved for moderately trusted environments. Bitcoin transactions are automatically signed according to preset user parameters.

  • Untrusted : This mode is the default mode when using standard operation parameters. Each bitcoin transaction has to be authorized.

  • Untrusted with transaction signing disabled : This mode should be enabled to only generate addresses on a server or offline wallet.

The persistent operation mode will be restored when the dongle is powered on.

The user is always authorized to move from an operation mode to a more restrictive operation mode. However an authentication is required to move to a less restrictive operation mode.

5.1. Fully trusted operation mode

All dongle functionalities are enabled in trusted mode. Arbitrary data can be signed by the dongle.

5.2. Moderately trusted operation mode

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

The standard script is coded as

OP_DUP OP_HASH160 [pubKeyHash] OP_EQUALVERIFY OP_CHECKSIG

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

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

  • A maximum output amount

  • A maximum fees amount

  • A maximum change amount

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

  • Only authorizing an output address that has been registered previously

5.3. Untrusted operation mode

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

The standard script is coded as

OP_DUP OP_HASH160 [pubKeyHash] OP_EQUALVERIFY OP_CHECKSIG

Each transaction has to be authenticated by the user given :

  • the output address

  • the output amount

  • the fees amount

  • the change private key address generated by the dongle

A cryptographic hash is computed over the transaction data by an external system displaying the authorization data for user validation (smartphone, remote server …) and sent back to the dongle to authenticate the transaction.

5.4. Untrusted operation mode with transaction signing disabled

In this mode, only the GENERATE KEYPAIR OR IMPORT PRIVATE KEY function is enabled, and all cleartext key import functionalities are disabled for this command (the only authorized import is option 08 : diversification of a given value)

5.5. Disabled dongle functionalities

When not operating in fully trusted mode, the following operations are disabled :

  • Authentication with a GlobalPlatform keyset other than 0x10 or 0xFE is disabled - to prevent accidental data leaks in an untrusted environment

  • CREATE FILE - to prevent a malware from creating arbitrary transaction control rules if an accidental key leak occured by authenticating with keyset 0x10 in an untrusted environment

  • PUT KEY

  • SYSTEM ADMINISTRATION - RESET if not authenticated with keyset 0x10

6. Additional keyset types

The following keyset types are added - only the first key component of the keysets is used for all types.

  • 20 : Private key encryption - these keys are used to encrypt private keys

  • 21 : Context exchange encryption - these keys are used to transfer contexts between dongles to make the transaction parsing mechanism stateless if desired

  • 22 : Authorized address encryption - these keys are used to encrypt authorized addresses

  • 23 : Trusted Input encryption - these keys are used to encrypt trusted inputs (previous output + amount extracted from a transaction)

  • 24 : Transaction authorization signature - these keys are used to sign transaction authorizations

  • 25 : Trusted Secure Channel - commands sent over a Secure Channel opened by such keyset will be executed in trusted mode, if at least command confidentiality (CMAC) is activated for this Secure Channel.

  • 26 : Private key signature - these keys are used to compute a signature of the generated private key

  • 27 : Mode signature - these keys are used to compute a signature of the operation mode returned by the dongle

  • 28 : Private key diversification - these keys are used to derive given values to generate a private key component

The first Key Access parameters byte is coded as per the other keys, and the second byte is not used.

The following key types are safe to share with an external device for the process integrity validation - other keys should never be shared with an external device, other than a backup dongle :

  • Private key signature : these keys will be used to check that a generated private key has not been held by a malware application (ransomware attack).

  • Transaction authorization signature : these keys will be used to authorize individual transactions.

Note
the Private key encryption key are the only keys that must be backed up properly by the user to be able to regenerate another dongle or retrieve private keys if the dongle is lost or destroyed.

7. Unique Internal Keypair

7.1. Description

It is possible to store a unique keypair into the dongle, never revealing the private key.

This private key cannot be backed up, and is mostly intended to exchange bitcoins between remote peers with no previously established trust relationship and be sure that the sender is not able to spend the coins sent to the receiver.

In this typical scenario, Sarah wants to send some coins to Rachel :

  • Sarah gets a blank BTChip dongle

  • Sarah asks Rachel to pick a password, and generate the Unique Internal Keypair, protected by Rachel’s password.

  • Sarah provides the Public Key of the Unique Internal Keypair to Rachel

  • Sarah sends the blank BTChip dongle to Rachel via snail mail

  • While the dongle travels around, Sarah, Boris, Brenda and Bob send coins to Rachel’s Public Key

  • Rachel receives the dongle, unlocks the Unique Internal Keypair with the previously chosen password, and can spend the coins.

7.2. Technical details

The private key is stored into the encrypted non readable file /uik

Before generating the Unique Internal Keypair, keyset 0xFD must be present with a GlobalPlatform Authentication Role.

Keyset 0xFD is automatically deleted on the first successful authentication.

The private component of the Unique Internal Keypair cannot be used while keyset 0xFD exists.

In all APIs the private key of the Unique Internal Keypair is referenced as an encrypted private key component beginning with "UIK" (55494B)

8. Additional files

8.1. Elliptic curve parameters

Elliptic curve parameters are stored in transparent files in 3F00/CE15 DF, using the following format

Description

Length

Size of A component

1

A component

var

Size of B component

1

B component

var

Size of Field component

1

Field component

var

Size of G component

1

G component

var

Size of R component

1

R component

var

Size of K component

1

K component

var

The secp256k1 bitcoin curve is provided in the 0xb1c0 file, and cannot be updated by the user.

Access conditions for the 0xb1c0 file are :

  • READ ALWays

  • UPDATE NEVer

  • DELETE NEVer

8.2. Operation parameters

Operation parameters are defined in the 0xb101 file located in 0x3f00. They define the basic functionalities of the dongle

Description

Length

Current operation mode

0x01 : trusted

0x02 : moderately trusted

0x04 : untrusted (default)

0x08 : untrusted with transaction signing disabled

1

Enforcement flag

0x01 : enforce maximum number of consecutive transactions

0x02 : enforce maximum cumulative output

1

Maximum number of consecutive transactions in the same session

2

Maximum cumulative output amount in the same session

8

Access conditions for this file are :

  • READ 0x01 (default user keyset)

  • UPDATE 0x01 (default user keyset)

  • DELETE 0xFE (administrative keyset)

8.3. Transaction control

Transaction control parameters are stored in transparent files in 3F00/0D11 DF, and are used to set generic rules for controlling transactions in moderately trusted mode, using the following format

Description

Length

Flags

0x01 : only accept pre-authorized output addresses

0x02 : check maximum output amount

0x04 : check maximum fee amount

0x08 : check maximum change amount

1

Maximum output amount, big endian

8

Minimum sequence index (apply to all inputs), big endian

4

Maximum sequence index (apply to all inputs), big endian

4

Minimum lock time

4

Maximum lock time

4

Bitmask of authorized SigHash values

0x01 : SIGHASH_ALL authorized

0x02 : SIGHASH_NONE authorized

0x04 : SIGHASH_SINGLE authorized

0x08 : mask SIGHASH_ANYONECANPAY authorized

1

Maximum fee amount, big endian

8

Maximum change amount, big endian

8

A default configuration file for payments up to 1 BTC is provided in the 0x0001 file, and cannot be updated by the user, using the following values :

  • Flags : 0x0E (check maximum output amount, maximum fee amount, maximum charge amount) in moderately trusted mode

  • Maximum output amount : 00 10 5E 5F 00 00 00 00 (1.000000000)

  • Maximum fee amount : 00 10 5E 5F 00 00 00 00 (1.000000000)

  • Maximum change amount : 00 10 5E 5F 00 00 00 00 (1.000000000)

  • Minimum sequence index : FF FF FF FF

  • Maximum sequence index : FF FF FF FF

  • Minimum lock time : 00 00 00 00

  • Maximum lock time : 00 00 00 00

  • Bitmask of authorized SigHash values : 0x01

Access conditions for the 0x0001 file are :

  • READ ALWays

  • UPDATE 0xFE (administrative keyset)

  • DELETE 0xFE (administrative keyset)

9. APDUs available for all modes

9.1. SET OPERATION MODE

9.1.1. Description

This command is used to set the operation mode of the dongle.

Going to a more restrictive operation mode is always authorized.

If going to a less restrictive operation mode, the user shall be authenticated by the GlobalPlatform user key 0x10.

The operation mode signature can be used by an external device to make sure that the mode switch is legitimate - it is computed as the last block of a 3DES-CBC encryption of the returned operation mode concatenated with the nonce.

9.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

24

target mode or 00 to query the current operation mode

01 : trusted mode

02 : moderately trusted mode

04 : untrusted mode

08 : untrusted mode with transaction signing disabled

00 : persistent change

80 : non persistent change done until powered down (only if going to a less restrictive mode)

01

10

Input data

Description

Length

Version of the keyset used for operation mode signature

1

Output data

Description

Length

Current operation mode

1

Nonce

F

Operation mode signature

8

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

9.2. GENERATE KEYPAIR OR IMPORT PRIVATE KEY

9.2.1. Description

This command is used to generate a keypair using the given curve parameters or import a given private key.

The file containing the curve parameter shall be selected before calling this command when generating a keypair.

The private part of the keypair will be encrypted by the Private key encryption key version passed as input parameter. This key must be accessible when the function is called

The private key signature can be used by an external device to make sure that a generated key is legitimate - it is computed as the last block of a 3DES-CBC encryption of the encrypted private key component concatenated with the derivation data.

If generating the Unique Internal Keypair

  • The Unique Internal Keypair must not exist

  • Keyset 0xFD must be present and set to GlobalPlatform Authentication Role

9.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

20

00 : generate mode

01 : provide Authorized Address for public key (not authorized when preparing a key in non trusted mode)

02 : on prepare mode, import private key in base-58 Wallet Import Format

04 : on prepare mode, import private key as a SHA-256 hash of the given data

08 : on prepare mode, 3DES-CBC encrypt the given binary value with the key passed in P2 and use this value as private key. The key passed in P2 must have the Bitcoin Key Derivation role

10 : generate the Unique Internal Keypair

80 : prepare mode, default import format being a binary key

00 or keyset version used to derive the provided data if using prepare mode with option 08

var

var

Input data

Description

Length

Version of the private key encryption keyset to use

1

Version of the private key signature keyset to use

1

Keypair flags

01 : key can only be used in trusted mode

02 : key is always reused as change address

1

File ID of the curve to use to generate this key

2

If requesting an Authorized Address, Authorized Address Encryption keyset version to use

1

if requesting an Authorized Address, Bitcoin address version

1

If importing a key, private key to encode / derivation data

var

Output data

Description

Length

Length of public key component (41)

1

Public key component (W)

41

Length of encrypted private key component (28)

1

Encrypted private key component (encrypted S)

28

Derivation data used (or 00…00)

20

Private key signature

8

If generating an Authorized Address, length of the Authorized Address (20)

1

If generating an Authorized Address, Authorized address

28

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

9.3. GET PUBLIC KEY

9.3.1. Description

This command is used to retrieve the public given given an encrypted private key.

The private part of the keypair should be be encrypted by the Private key encryption key version passed as input parameter. This key must be accessible when the function is called

9.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

26

00

00

var

var

Input data

Description

Length

Version of the private key encryption to use

1

Encrypted private key

var

Output data

Description

Length

Public key component (W)

41

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

10. Trusted operation mode APDUs

10.1. AUTHORIZE ADDRESS

10.1.1. Description

This command is used to encode an address authorization.

The address is an hash160 (ripemd160 of a sha256) of an ECDSA public key, encoded using base58 or provided as binary data.

The authorized address will be encrypted by the Authorized address encryption version passed as input parameter.

This key must be accessible when the function is called

10.1.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

22

00 : address provided as a base58 string (if supported)

80 : address provided as a version byte + hash160

00

var

var

Input data

Description

Length

Version of the Authorized address encryption key to use

1

Address size

1

Address to authorize

var

Output data

Description

Length

Authorized address

28

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

10.2. ECDSA SIGN/VERIFY IMMEDIATE

10.2.1. Description

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

The private key shall be encrypted by the Private key encryption key version passed as input parameter. This key must be accessible when the function is called

If a signature is required in untrusted mode, this command will exit with status word 0x6982

10.2.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

40

00 : sign

80 : verify

00

var

var

Input data (sign mode)

Description

Length

Version of the private key encryption to use

1

Length of encrypted private key

1

Encrypted private key

var

Hash to sign

var

Input data (verify mode)

Description

Length

File ID of the curve to use to verify the signature

2

Length of public key

1

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

var

Output data (verify mode)

None

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

Security status not satisfied (running in untrusted mode)

6A80

Invalid data (invalid key encryption)

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

11. APDUs available for moderately trusted and untrusted modes

11.1. GET TRUSTED INPUT

11.1.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.

11.1.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

Keyset version used for Trusted Input encryption

1

Input index to lookup

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

38

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A80

Invalid data (parameters or transaction data)

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

11.2. UNTRUSTED HASH TRANSACTION INPUT START

11.2.1. Description

This command is used to compose an opaque SHA-256 hash for a new transaction, controlled by the given transaction control file.

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

  • Each input outpoint is to be replaced by its associated Trusted Input encryption key (1 byte), 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, 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.

11.2.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 (first transaction data block for a new transaction)

Description

Length

File ID of the transaction control file to use for generic rules regarding this transaction, or 0000 (forbidden for moderately trusted mode)

2

Transaction data

var

Input data (other transaction data block)

Description

Length

Transaction data

var

Output data

None

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A80

Invalid data (parameters or transaction data)

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

11.3. UNTRUSTED HASH TRANSACTION INPUT FINALIZE

11.3.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.

OP_DUP OP_HASH160 [pubKeyHash] OP_EQUALVERIFY OP_CHECKSIG

The output amount, fees and change will be optionally enforced in moderately trusted mode given the transaction control file used for this transaction

In untrusted mode, an authorization will be computed for the transaction using the output address, the output amount, the fees, change address and a hash of the transaction not including input script data.

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

11.3.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

46

01 : output address provided as binary hash160

02 : output address provided as base58 string (if supported)

03 : output address provided as authorized address

Authorized Address encryption keyset version used if providing the output address as an Authorized Address

var

var

Input data (first input processed for a given transaction)

Description

Length

Version of the private key encryption to use for the Change Address

1

Length of the Output Address

1

Output Address (base58, hash160 or Authorized Address)

var

Length of the Change Address Private Key

1

Change Address (as an encrypted private key)

var

Amount (big endian)

8

Fees (big endian)

8

Input data (other input for the same transaction)

None

Output data (first input processed for a given transaction)

Description

Length

Generated transaction output data length

1

Generated transaction output data

var

Transaction Authorization Data length

1

Transaction Authorization Data if necessary

var

Output data (other input for the same transaction)

None

Transaction Authorization data

Description

Length

Transaction hash not including input script data

20

Transaction Nonce

8

Output address as hash160

14

Output amount

8

Fees amount

8

Change amount

8

Change Address encryption keyset version

1

Length of the Change Address Private Key

1

Change Address (as an encrypted private key)

28

Change public key hash160

14

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A80

Invalid data (parameters, transaction state or rules not validated)

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

11.4. UNTRUSTED HASH SIGN

11.4.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 Transaction Authorization is required and the provided Transaction Authorization signature is not correct.

The private key shall be encrypted by the Private key encryption key version passed as input parameter. This key must be accessible when the function is called

The locktime and SigHash value will be enforced given the transaction control file used for this transaction

11.4.2. Coding

Command

CLA

INS

P1

P2

Lc

Le

E0

48

00

00

var

var

Input data

Description

Length

Version of the private key encryption keyset to use

1

Length of encrypted private key

1

Encrypted private key

var

Version of the Transaction Authorization signature keyset to use (or 00)

1

Length of the Transaction Authorization Signature (or 00)

1

Transaction Authorization Signature if provided

var

Lock Time (big endian)

4

SigHashType

1

Output data

Description

Length

Signed hash, as ASN-1 encoded R & S components

var

SigHashType

1

Licensing

This function is always available

Status Words

SW

Description

6581

Memory problem

6700

Incorrect length

6982

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

6A82

File not found

6B00

Incorrect parameter P1 or P2

6Fxx

Technical problem (00 : no diagnostic given)

9000

Normal ending of the command

9804

Access condition not fulfilled

11.5. TRANSACTION CONTEXT IMPORT/EXPORT

RFU.

12. 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.

12.1. Encoded private key for a 256 bits curve

An encoded private key is stored internally as follow, Triple DES encrypted by the private key encryption key

Description

Length

Magic version (01)

1

Private key flags (RFU)

1

ID of the file in 3F00/CE15 containing the curve parameters

2

CRC-16 of the structure computed after setting current bytes to 0000

2

Nonce

2

Private key component (S)

20

12.2. Encoded authorized address

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

Description

Length

Magic version (21)

1

Public key flags (RFU)

1

RFU (00)

1

Nonce

8

Bitcoin address version

1

Bitcoin address as a hash160

14

Signature

8

12.3. 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 (31)

1

Nonce

3

Associated transaction hash

20

Index in associated transaction

4

Associated amount

8

Signature

8

12.4. Transaction context for dongle exchange

RFU.