API (v2.2)

A simple JSON interface allows developers to quickly make use of a Digital Bitbox. The Digital Bitbox is a plug-n-play USB-HID device and can be accessed using the C/C++ [HID API library](http://www.signal11.us/oss/hidapi/) or one of its ports to a different language. The [Digital Bitbox code](https://github.com/digitalbitbox/mcu) is open source on GitHub. A [native cross-platform desktop app](https://github.com/digitalbitbox/dbb-app) provides a client interface for a fully functioning wallet. Two-factor authentication (2FA) using a [mobile app](https://github.com/digitalbitbox/2FA-app) provides a remote screen for added security. The Digital Bitbox microcontroller code, written in C, can be compiled and run as a standalone program on a PC for testing purposes. A list of API commands is provided below. The Digital Bitbox's hierarchical deterministic wallet structure follows the BIP32 and BIP44 standards. Wallets are securely generated onboard the Digital Bitbox using a high-quality [hardware random number generator](http://www.atmel.com/devices/ATAES132A.aspx) to produce entropy. Alternatively, users can load their own wallet either from a file on a micro SD card or through the USB interface. The micro SD port allows offline backup of the wallet to a file. Random numbers can be requested via the USB interface in order to verify their quality or to use them in other applications. All USB communication is password encrypted using the AES-256-CBC algorithm with base-64 encoding. USB packets are sent following the ISO 7816-4 standard. A password must be set before any command is accepted. Brute force password attacks are not possible as the device will reset and erase all private data after 15 incorrect tries. In case a password is forgotten, reset the device and reload your wallet from the backup on the micro SD card.




Method & Parameters Response Notes

Generate a wallet on your Digital Bitbox

"seed" :
{
      "raw" : "true",
      "source" : "source",
      "entropy" : "entropy",
      "key" : "key",
      "filename" : "filename"
}

"seed" : "success"

Source:  create or backup. create securely creates a new wallet on the device and saves a backup filename to the micro SD card. backup creates a wallet from a backup filename on the micro SD card. key is the passphrase used when cryptographically generating a wallet. The key is recommended to be strengthened (e.g. PBKDF2) by the client software in order to make brute force attacks on the backup more difficult.

entropy and raw are optional when using the create mode. User-supplied entropy can be added to the output of the device's hardware random number generator when creating a wallet. When 'raw':'true' is specified, only the user-supplied entropy, which is used when creating a wallet, useful for conducting deterministic unit tests.


Backup the existing wallet to a micro SD card

"backup" :
{
      "key" : "key",
      "filename" : "filename"
}

"backup" : "success"

Saves a backup of the wallet to a file filename in a digitalbitbox folder on the micro SD card. key is the wallet passphrase and used to verify the integrity of the saved file. The SD card should be formatted (FAT file system) before use.

"backup" : "list"

"backup" : "files"

Lists the files and folders in the digitalbitbox/ folder on the micro SD card.

"backup" :
{
      "check" : "filename",
      "key" : "key"
}

"backup" : "success"

Check if the backup filename on the micro SD card, protected by the key passphrase matches the seeded wallet.

"backup" : "erase"

"backup" : "success"

Erase everything in the digitalbitbox/ folder on the micro SD card.

"backup" :
{
      "erase" : "filename"
}

"backup" : "success"

Erase filename in the digitalbitbox/ folder on the micro SD card.


Set a password

"password" : "password"

"password" : "success"

A password is required that has a length of at least 4 characters. The password needs to be sent only once and is used to encrypt all communication via the AES-256-CBC algorithm.


Access a hidden wallet

"hidden password" : "hidden_password"

"hidden password" : "success"

As a plausible deniability security feature, once set, a hidden password can be used to access a hidden wallet.


Sign using a private key

"sign" :
{
      "meta" : "metadata",
      "data" : "hasharray",
      "checkpub" : "pubkeyarray"
}

"echo" :
{
      "meta" : "metadata",
      "data" : "hasharray",
      "checkpub" : "pubkeyarray",
      "pin" : "lock_pin"
}

The sign command produces ECDSA signatures of hashes given in data. Two sign commands must be sent in a row. The first command produces an encrypted verfication message. The second command (see below) returns an array of signatures and corresponding signing pubkeys. Verification messages allow two-factor authentication (2FA) for highest security.

Data:  hasharray contains a list of hashes and the keypaths used to sign each hash: [{'hash':'hash 1', 'keypath':'keypath 1'}, ... ]. Multiple hashes can be signed in one command. Each hash must be 64-characters long (representing a 32-byte hexadecimal value).

Checkpub:  pubkeyarray contains a list of compressed pubkeys and associated keypaths. This is used for checking if a pubkey, e.g. for a change output, is part of the wallet: [{'pubkey':'pubkey 1', 'keypath':'keypath 1'}, ... ]. Any number of pubkeys can be checked. The result is added to the encrypted verification message: [{'pubkey':'pubkey 1', 'present':true}, ... ].

Meta:  metadata is included 'as is' in the returned encrypted verfication message. This is typically a hash of the unsigned transaction.

The JSON value of the echo response is encrypted with the verification key (see verifypass below). For locked devices, the lock_pin is the single-use PIN required to 'unlock', or allow, signatures to be created and returned after sending the second sign command.

"sign" :
{
      "pin" : "lock_pin"
}

"sign" :
{
      "recid" : "recid",
      "sig" : "signature"
}

The second sign command turns on the LED for touch button user confirmation. Its reply contains the signatures. For an unlocked device, pin is ignored, and an empty command can be sent instead: {'sign': ''}.

Returned signatures are not post-processed. DER encoding for a standard transaction is to be done in the client software. recid is the recoverable ID that can be used to derive the public key from the signature. ECDSA signing without pre- or post-processing provides compatibility 'out-of-the-box' with multisignature protocols, altcoins, or other custom implementations.


Set a verification key for two-factor authentication (2FA)

"verifypass" : "operation"

"verifypass" : "reply"

Operation:  export, create, or {'ecdh': 'pubkey A'}. create uses the hardware random number generator to create a random 64 character hexadecimal string as a verification key. {'ecdh': 'pubkey'} implements Diffie-Hellman key exchange using the secp2561 elliptic curve. export saves the key to the micro SD card in a plaintext file named verification.txt.

The reply is success for create or export. For ecdh, the reply is {'ecdh': 'pubkey B'}. To avoid MITM from intercepting the shared ECDH secret, LED blinks (to be entered by hand on the 2FA device) are included in key creation. Watch for future tutorial videos for details.

2FA is used to verify that the correct transaction is signed even when using a fully compromised host computer. A verification key is generated during the factory installation and can be updated at any time by an owner. The verification message can be displayed and checked on a separate device (i.e. smartphone app or web service) that knows the verification key. The AES-256-CBC algorithm is used for encryption.

"device" : "lock"

"device" :
{
      "lock" : "boolean"
}

Disables backup, verifypass, and seed commands. These can be re-enabled only after a reset command. Be sure to backup your wallet before locking the device!

The verifypass command allows a second object to be used for verification. If a thief steals an unlocked Digital Bitbox and knows its password, the coins can be taken without the need for the second object. The lock command adds full 2FA protection by requiring the thief to also possess the second object in order to steal coins. After locking the Digital Bitbox, a single-use 4-digit PIN is included within the encrypted verification message and is displayed on the second object. This PIN is required to unlock (i.e. decrypt) the signed transaction before it is broadcast to the Bitcoin network.


Encrypt or decrypt text (AES 256 CBC)

"aes256cbc" :
{
      "type" : "password",
      "data" : "password"
}

"aes256cbc" : "success"

Set the AES key as the double SHA256 of the password. The AES key is stored onboard in non-volatile memory, which has a specified minimum lifespan of 100,000 write cycles.

"aes256cbc" :
{
      "type" : "xpub",
      "data" : "keypath"
}

"aes256cbc" : "success"

Set the AES key as the double SHA256 of the extended public key located at the given keypath.

"aes256cbc" :
{
      "type" : "type",
      "data" : "data"
}

"aes256cbc" : "reply"

Type:  encrypt, decrypt, or verify. encrypt and decrypt use the AES key set by the type password or xpub commands. verify performs (only) encryption using the verification password set using the verifypass command.

Data:  the data to encrypt / decrypt. Encrypted data is base-64 encoded.


Reset

"reset" : "__ERASE__"

"reset" : "success"

Factory resets the wallet and erases all wallet data. U2F second-factor authentication data is NOT reset.

"reset" : "U2F"

"reset" : "success"

Replaces the U2F second-factor authentication master key with a new random key. Existing U2F second-factor authentication pairings are lost and CANNOT be recovered.


Name the device

"name" : "name"

"name" : "name"

Saves a new name. Long names are truncated to 32 characters. Sending an empty string will return the current name.


Blink the LED

"led" : "mode"

"led" : "success"

mode is blink or abort. The latter reproduces the LED blinks that occur when a user aborts an operation that requires touch confirmation.


Get a random number from the device

"random" : "mode"

"random" : "number"

Mode:  true or pseudo.

A 16 byte random number is returned as a hexadecimal string. The hardware random number generator (RNG) on a high-security crypto chip is used. The true RNG mode updates a seed value written to the chip's EEPROM, which has a specified minimum lifespan of 100,000 write cycles. The pseudo RNG mode derives numbers using this seed and does not affect lifespan.


Get an extended public key at the indicated keypath

"xpub" : "keypath"

"xpub" : "xpub"

"echo" : "encrypted_xpub"

Returns the xpub for the given keypath, for example, m/purpose'/coin_type'/account'/change/address_index, following the BIP44 standard. An apostrophe designates a hardened key derivation. A letter p, h, or H can be used instead of an apostrophe. In practice, the Digital Bitbox wallet is agnostic of the keypath, i.e., m/index_1/index_2/index_3/...index_N is valid for a varying number of N indices. Each index can be designated as hardened or not. The keypath to return the extended master public key is m/.

The echo returns the extended public key encrypted using the 2FA verification key.


Set access to the bootloader

"bootloader" : "status"

"bootloader" : "status"

status is lock or unlock. When unlocked, the bootloader is entered by pressing the touch button within 3 seconds of plugging in the device. Otherwise, the firmware starts.


Get device information

"device" : "info"

"device" :
{
      "seeded" : "boolean",
      "name" : "name",
      "U2F" : "boolean",
      "lock" : "boolean",
      "sdcard" : "boolean",
      "bootlock" : "boolean",
      "version" : "version",
      "U2F_hijack" : "boolean",
      "serial" : "number",
      "id" : "sha(xpub)"
}

id is a SHA256 hash of the master extended public key if seeded.


Feature options

"feature_set" :
{
      "U2F" : "boolean",
      "U2F_hijack" : "boolean"
}

"feature_set" : "success"

U2F enables or disables the U2F second-factor authentication function. If disabled, any U2F commands will be answered with a device busy error message. Enabled by default on factory reset.

U2F_hijack enables or disables browser access to the hardware wallet API. Communication is done by hijacking the 'key handle' data field of the U2F authentication command. This must be enabled to use any web integrations, such as MyEtherWallet. If U2F is disabled, U2F_hijack will also be disabled, even if it is set to be enabled. When disabled, any U2F hijack commands will be answered with a device busy error message. Enabled by default on factory reset.

boolean should be true or false and without quotes. A single feature or any combination of features can be sent.