bitbox02

Documentation

Overview

Package bitbox02 contains the API to the physical device.

Package bitbox02 contains the API to the physical device.

Index

• Constants
• type Backup
• type Communication
• type Device
  • func NewDevice(deviceID string, version *semver.SemVer, edition bitbox02common.Edition, ...) *Device
  • func (device *Device) Attestation() bool
  • func (device *Device) BTCPub(coin messages.BTCCoin, keypath []uint32, ...) (string, error)
  • func (device *Device) BTCSign(btcProposedTx *btc.ProposedTransaction) ([]*btcec.Signature, error)
  • func (device *Device) ChannelHash() (string, bool)
  • func (device *Device) ChannelHashVerify(ok bool)
  • func (device *Device) CheckBackup(silent bool) (string, error)
  • func (device *Device) CheckSDCard() (bool, error)
  • func (device *Device) Close()
  • func (device *Device) CreateBackup() error
  • func (device *Device) DeviceInfo() (*DeviceInfo, error)
  • func (device *Device) ETHPub(coin messages.ETHCoin, keypath []uint32, ...) (string, error)
  • func (device *Device) ETHSign(coin messages.ETHCoin, keypath []uint32, nonce uint64, gasPrice *big.Int, ...) ([]byte, error)
  • func (device *Device) Edition() bitbox02common.Edition
  • func (device *Device) Identifier() string
  • func (device *Device) Init(testing bool) error
  • func (device *Device) InsertRemoveSDCard(action messages.InsertRemoveSDCardRequest_SDCardAction) error
  • func (device *Device) KeystoreForConfiguration(configuration *signing.Configuration, cosignerIndex int) keystoreInterface.Keystore
  • func (device *Device) ListBackups() ([]*Backup, error)
  • func (device *Device) ProductName() string
  • func (device *Device) Random() ([]byte, error)
  • func (device *Device) Reset() error
  • func (device *Device) RestoreBackup(id string) error
  • func (device *Device) RestoreFromMnemonic() error
  • func (device *Device) SetDeviceName(deviceName string) error
  • func (device *Device) SetMnemonicPassphraseEnabled(enabled bool) error
  • func (device *Device) SetOnEvent(onEvent func(devicepkg.Event, interface{}))
  • func (device *Device) SetPassword() error
  • func (device *Device) ShowMnemonic() error
  • func (device *Device) Status() Status
  • func (device *Device) UpgradeFirmware() error
  • func (device *Device) Version() *semver.SemVer
• type DeviceInfo
• type Error
  • func NewError(code int32, message string) *Error
  • func (err *Error) Error() string
• type Status

Constants

const (
	// EventChannelHashChanged is fired when the return values of ChannelHash() change.
	EventChannelHashChanged device.Event = "channelHashChanged"

	// EventStatusChanged is fired when the status changes. Check the status using Status().
	EventStatusChanged device.Event = "statusChanged"

	// EventAttestationCheckFailed is fired when the device does not pass the attestation signature
	// check, indicating that it might not be an authentic device.
	EventAttestationCheckFailed device.Event = "attestationCheckFailed"
)

const (

	// ErrInvalidInput is returned when the request sends and invalid or unexpected input
	ErrInvalidInput = 101

	// ErrUserAbort is returned when the user aborts an action on the device.
	ErrUserAbort = 104
)

const ProductName = "bitbox02"

ProductName is the name of the BitBox02 product. If you change this, be sure to check the frontend and other places which assume this is a constant.

Types

type Backup

type Backup struct {
	ID   string
	Name string
	Time time.Time
}

Backup contains the metadata of one backup.

type Communication

type Communication interface {
	SendFrame(string) error
	ReadFrame() ([]byte, error)
	Close()
}

Communication contains functions needed to communicate with the device.

type Device

type Device struct {
	// contains filtered or unexported fields
}

Device provides the API to communicate with the BitBox02.

func NewDevice

func NewDevice(
	deviceID string,
	version *semver.SemVer,
	edition bitbox02common.Edition,
	configDir string,
	communication Communication,
) *Device

NewDevice creates a new instance of Device.

func (*Device) Attestation

func (device *Device) Attestation() bool

Attestation returns the result of the automatic attestation check.

func (*Device) BTCPub

func (device *Device) BTCPub(
	coin messages.BTCCoin,
	keypath []uint32,
	outputType messages.BTCPubRequest_OutputType,
	scriptType messages.BTCScriptType,
	display bool) (string, error)

BTCPub queries the device for a btc, ltc, tbtc, tltc xpub or address.

func (*Device) BTCSign

func (device *Device) BTCSign(
	btcProposedTx *btc.ProposedTransaction) ([]*btcec.Signature, error)

BTCSign signs a bitcoin or bitcoin-like transaction.

func (*Device) ChannelHash

func (device *Device) ChannelHash() (string, bool)

ChannelHash returns the hashed handshake channel binding

func (*Device) ChannelHashVerify

func (device *Device) ChannelHashVerify(ok bool)

ChannelHashVerify verifies the ChannelHash

func (*Device) CheckBackup

func (device *Device) CheckBackup(silent bool) (string, error)

CheckBackup checks if any backup on the SD card matches the current seed on the device and returns the name and ID of the matching backup

func (*Device) CheckSDCard

func (device *Device) CheckSDCard() (bool, error)

CheckSDCard checks whether an sd card is inserted in the device

func (*Device) Close

func (device *Device) Close()

Close implements device.Device.

func (*Device) CreateBackup

func (device *Device) CreateBackup() error

CreateBackup is called after SetPassword() to create the backup.

func (*Device) DeviceInfo

func (device *Device) DeviceInfo() (*DeviceInfo, error)

DeviceInfo retrieves the current device info from the bitbox

func (*Device) ETHPub

func (device *Device) ETHPub(
	coin messages.ETHCoin,
	keypath []uint32,
	outputType messages.ETHPubRequest_OutputType,
	display bool,
	contractAddress []byte,
) (string, error)

ETHPub queries the device for an ethereum address or publickey.

func (*Device) ETHSign

func (device *Device) ETHSign(
	coin messages.ETHCoin,
	keypath []uint32,
	nonce uint64,
	gasPrice *big.Int,
	gasLimit uint64,
	recipient [20]byte,
	value *big.Int,
	data []byte) ([]byte, error)

ETHSign signs an ethereum transaction. It returns a 65 byte signature (R, S, and 1 byte recID).

func (*Device) Edition

func (device *Device) Edition() bitbox02common.Edition

Edition returns the device edition.

func (*Device) Identifier

func (device *Device) Identifier() string

Identifier implements device.Device.

func (*Device) Init

func (device *Device) Init(testing bool) error

Init implements device.Device.

func (*Device) InsertRemoveSDCard

func (device *Device) InsertRemoveSDCard(action messages.InsertRemoveSDCardRequest_SDCardAction) error

InsertRemoveSDCard sends a command to the device to insert of remove the sd card based on the workflow state

func (*Device) KeystoreForConfiguration

func (device *Device) KeystoreForConfiguration(configuration *signing.Configuration, cosignerIndex int) keystoreInterface.Keystore

KeystoreForConfiguration implements device.Device.

func (*Device) ListBackups

func (device *Device) ListBackups() ([]*Backup, error)

ListBackups returns a list of all backups on the SD card.

func (*Device) ProductName

func (device *Device) ProductName() string

ProductName implements device.Device.

func (*Device) Random

func (device *Device) Random() ([]byte, error)

Random requests a random number from the device using protobuf messages

func (*Device) Reset

func (device *Device) Reset() error

Reset factory resets the device.

func (*Device) RestoreBackup

func (device *Device) RestoreBackup(id string) error

RestoreBackup restores a backup returned by ListBackups (id).

func (*Device) RestoreFromMnemonic

func (device *Device) RestoreFromMnemonic() error

RestoreFromMnemonic invokes the mnemonic phrase import workflow.

func (*Device) SetDeviceName

func (device *Device) SetDeviceName(deviceName string) error

SetDeviceName sends a request to the device using protobuf to set the device name

func (*Device) SetMnemonicPassphraseEnabled

func (device *Device) SetMnemonicPassphraseEnabled(enabled bool) error

SetMnemonicPassphraseEnabled enables or disables entering a mnemonic passphrase after the normal unlock.

func (*Device) SetOnEvent

func (device *Device) SetOnEvent(onEvent func(devicepkg.Event, interface{}))

SetOnEvent implements device.Device.

func (*Device) SetPassword

func (device *Device) SetPassword() error

SetPassword invokes the set password workflow on the device. Should be called only if deviceInfo.Initialized is false.

func (*Device) ShowMnemonic

func (device *Device) ShowMnemonic() error

ShowMnemonic lets the user export the bip39 mnemonic phrase on the device.

func (*Device) Status

func (device *Device) Status() Status

Status returns the device state. See the Status* constants.

func (*Device) UpgradeFirmware

func (device *Device) UpgradeFirmware() error

UpgradeFirmware reboots into the bootloader so a firmware can be flashed.

func (*Device) Version

func (device *Device) Version() *semver.SemVer

Version returns the firmware version.

type DeviceInfo

type DeviceInfo struct {
	Name                      string `json:"name"`
	Version                   string `json:"version"`
	Initialized               bool   `json:"initialized"`
	MnemonicPassphraseEnabled bool   `json:"mnemonicPassphraseEnabled"`
}

DeviceInfo is the data returned from the device info api call.

type Error

type Error struct {
	Code    int32
	Message string
}

Error wraps an error from bitbox02.

func NewError

func NewError(code int32, message string) *Error

NewError creates a error with the given message and code.

func (*Error) Error

func (err *Error) Error() string

Error implements the error interface.

type Status

type Status string

Status represents the device status.

const (
	// StatusConnected ist the first status, right after the device is connected. We automatically
	// move to StatusUnpaired (directly if the device is uninitialized, or after unlocking the
	// device if it is initialzed).
	StatusConnected = "connected"

	// StatusUnpaired means the pairing has not been confirmed yet. After the pairing screen has
	// been confirmed, we move to StatusUninitialized or StatusInitialized depending on the device
	// status.
	StatusUnpaired Status = "unpaired"

	// StatusPairingFailed is when the pairing code was rejected on the app or on the device.
	StatusPairingFailed Status = "pairingFailed"

	// StatusUninitialized is the uninitialized device. Use SetPassword() to proceed to
	// StatusSeeded.
	StatusUninitialized Status = "uninitialized"

	// StatusSeeded is after SetPassword(), before CreateBack() during initialization of the
	// device. Use CreateBackup() to move to StatusInitialized.
	StatusSeeded Status = "seeded"

	// StatusInitialized means the device is seeded and the backup was created, and the device is
	// unlocked. The keystore is ready to use.
	StatusInitialized Status = "initialized"

	// StatusRequireFirmwareUpgrade means that the a firmware upgrade is required before being able
	// to proceed to StatusLoggedIn or StatusSeeded (firmware version too old).
	StatusRequireFirmwareUpgrade Status = "require_firmware_upgrade"

	// StatusRequireAppUpgrade means that the an app upgrade is required (firmware version too new).
	StatusRequireAppUpgrade Status = "require_app_upgrade"
)