firmware

package
v0.0.0-...-35af5fe Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2025 License: Apache-2.0 Imports: 31 Imported by: 4

Documentation

Overview

Package firmware contains the API to the physical device.

Index

Constants

View Source 
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
)

Variables

This section is empty.

Functions

func BTCSignNeedsPrevTxs 

func BTCSignNeedsPrevTxs(scriptConfigs []*messages.BTCScriptConfigWithKeypath) bool

BTCSignNeedsPrevTxs returns true if the PrevTx field in BTCTxInput needs to be populated before calling BTCSign(). This is the case if there are any non-taproot inputs in the transaction to be signed.

func DecodeSilentPaymentAddress 

func DecodeSilentPaymentAddress(address string) (string, *btcec.PublicKey, *btcec.PublicKey, error)

DecodeSilentPaymentAddress decodes a slient payment address, returning the bech32 HRP and the scan/spend pubkeys.

func ETHIdentifyCase 

func ETHIdentifyCase(recipientAddress string) messages.ETHAddressCase

ETHIdentifyCase identifies the case of the recipient address given as hexadecimal string. This function exists as a convenience to potentially help clients to determine the case of the recipient address. The output of the function goes to ETHSign and ETHSignEIP1559 as the recipientAddressCase parameter, which is forwarded to BitBox02 device to reconstruct the address in the correct case(the one that the user enters).

func IsErrorAbort 

func IsErrorAbort(err error) bool

IsErrorAbort returns whether the user aborted the operation.

func NewBTCScriptConfigMultisig 

func NewBTCScriptConfigMultisig(
	threshold uint32,
	xpubs []string,
	ourXPubIndex uint32,
) (*messages.BTCScriptConfig, error)

NewBTCScriptConfigMultisig is a helper to construct the a multisig script config.

func NewBTCScriptConfigPolicy 

func NewBTCScriptConfigPolicy(policy string, keys []*messages.KeyOriginInfo) *messages.BTCScriptConfig

NewBTCScriptConfigPolicy is a helper to construct the a BIP-388 wallet policy script config.

func NewBTCScriptConfigSimple 

func NewBTCScriptConfigSimple(typ messages.BTCScriptConfig_SimpleType) *messages.BTCScriptConfig

NewBTCScriptConfigSimple is a helper to construct the correct script config for simple script types.

func NewXPub 

func NewXPub(xpub string) (*messages.XPub, error)

NewXPub parses an xpub string into an XPub protobuf message. The XPub version is not checked an discarded.

Types

type BTCPrevTx 

type BTCPrevTx struct {
	Version  uint32
	Inputs   []*messages.BTCPrevTxInputRequest
	Outputs  []*messages.BTCPrevTxOutputRequest
	Locktime uint32
}

BTCPrevTx is the transaction referenced by an input.

func NewBTCPrevTxFromBtcd 

func NewBTCPrevTxFromBtcd(tx *wire.MsgTx) *BTCPrevTx

NewBTCPrevTxFromBtcd converts a btcd transaction to a BTCPrevTx.

type BTCSignMessageResult 

type BTCSignMessageResult struct {
	// Signature is the 64 byte raw signature.
	Signature []byte
	// RecID is the recoverable ID.
	RecID byte
	// ElectrumSig65 is the 65 byte signature in Electrum format.
	ElectrumSig65 []byte
}

BTCSignMessageResult is the result of `BTCSignMessage()`.

type BTCSignResult 

type BTCSignResult struct {
	// Signatures contains the input signatures. One 64 byte signature per input.
	Signatures [][]byte
	// GeneratedOutputs contains the outputs generated (silent payments). The map key is the input
	// index, the map value is the generated pkScript.
	GeneratedOutputs map[int][]byte
}

BTCSignResult is the result of `BTCSign()`.

type BTCTx 

type BTCTx struct {
	Version         uint32
	Inputs          []*BTCTxInput
	Outputs         []*messages.BTCSignOutputRequest
	Locktime        uint32
	PaymentRequests []*messages.BTCPaymentRequestRequest
}

BTCTx is the data needed to sign a btc transaction.

type BTCTxInput 

type BTCTxInput struct {
	Input *messages.BTCSignInputRequest
	// PrevTx must be the transaction referenced by Input.PrevOutHash. Can be nil if
	// `BTCSignNeedsPrevTxs()` returns false.
	PrevTx *BTCPrevTx
	// Required for silent payment address verification.
	//
	// Public key according to
	// https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki#user-content-Inputs_For_Shared_Secret_Derivation.
	// Must be 33 bytes for a regular pubkey, and 32 bytes in case of a Taproot x-only output
	// pubkey.
	//
	// IMPORTANT: for Taproot inputs, you must provide the 32 byte x-only pubkey, not a 33 byte
	// pubkey, otherwise the parity of the Y coordinate could be wrong.
	BIP352Pubkey []byte
}

BTCTxInput contains the data needed to sign an input.

type Backup 

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

Backup contains the metadata of one backup.

type BluetoothInfo 

type BluetoothInfo struct {
	// FirmwareHash is the hex-encoded 32 byte Bluetooth firmware hash.
	FirmwareHash string `json:"firmwareHash"`
	// FirmwareVersion is the Bluetooth firmware version, formated as "major.minor.patch".
	FirmwareVersion string `json:"firmwareVersion"`
	// Enabled is true if Bluetooth is enabled.
	Enabled bool `json:"enabled"`
}

BluetoothInfo contains Bluetooth-related info.

type Communication 

type Communication interface {
	Query([]byte) ([]byte, error)
	Close()
}

Communication contains functions needed to communicate with the device.

type ConfigInterface 

type ConfigInterface interface {
	// ContainsDeviceStaticPubkey returns true if a device pubkey has been added before.
	ContainsDeviceStaticPubkey(pubkey []byte) bool
	// AddDeviceStaticPubkey adds a device pubkey.
	AddDeviceStaticPubkey(pubkey []byte) error
	// GetAppNoiseStaticKeypair retrieves the app keypair. Returns nil if none has been set before.
	GetAppNoiseStaticKeypair() *noise.DHKey
	// SetAppNoiseStaticKeypair stores the app keypair. Overwrites keypair if one already exists.
	SetAppNoiseStaticKeypair(key *noise.DHKey) error
}

ConfigInterface lets the library client provide their own persisted config backend.

type Device 

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

Device provides the API to communicate with the BitBox02.

func NewDevice 

func NewDevice(
	version *semver.SemVer,
	product *common.Product,
	config ConfigInterface,
	communication Communication,
	log Logger,
	opts ...DeviceOption,
) *Device

NewDevice creates a new instance of Device. version: 

Can be given if known at the time of instantiation, e.g. by parsing the USB HID product string.
It must be provided if the version could be less than 4.3.0.
If nil, the version will be queried from the device using the OP_INFO api endpoint. Do this
when you are sure the firmware version is bigger or equal to 4.3.0.

product: same deal as with the version, after 4.3.0 it can be inferred by OP_INFO.

func (*Device) Attestation 

func (device *Device) Attestation() *bool

Attestation returns the result of the automatic attestation check. If nil, the check has not been completed yet.

func (*Device) BIP85AppBip39 

func (device *Device) BIP85AppBip39() error

BIP85AppBip39 invokes the BIP85-BIP39 workflow on the device, letting the user select the number of words (12, 28, 24) and an index and display a derived BIP-39 mnemonic.

func (*Device) BIP85AppLN 

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

BIP85AppLN invokes the BIP85-LN workflow on the device, returning 16 bytes of derived entropy for use with Breez-SDK.

func (*Device) BTCAddress 

func (device *Device) BTCAddress(
	coin messages.BTCCoin,
	keypath []uint32,
	scriptConfig *messages.BTCScriptConfig,
	display bool) (string, error)

BTCAddress queries the device for a btc, ltc, tbtc, tltc address.

func (*Device) BTCIsScriptConfigRegistered 

func (device *Device) BTCIsScriptConfigRegistered(
	coin messages.BTCCoin,
	scriptConfig *messages.BTCScriptConfig,
	keypathAccount []uint32,
) (bool, error)

BTCIsScriptConfigRegistered returns true if the script config / account is already registered.

func (*Device) BTCRegisterScriptConfig 

func (device *Device) BTCRegisterScriptConfig(
	coin messages.BTCCoin,
	scriptConfig *messages.BTCScriptConfig,
	keypathAccount []uint32,
	name string,
) error

BTCRegisterScriptConfig returns true if the script config / account is already registered.

func (*Device) BTCSign 

func (device *Device) BTCSign(
	coin messages.BTCCoin,
	scriptConfigs []*messages.BTCScriptConfigWithKeypath,
	outputScriptConfigs []*messages.BTCScriptConfigWithKeypath,
	tx *BTCTx,
	formatUnit messages.BTCSignInitRequest_FormatUnit,
) (*BTCSignResult, error)

BTCSign signs a bitcoin or bitcoin-like transaction. The previous transactions of the inputs need to be provided if `BTCSignNeedsPrevTxs()` returns true.

func (*Device) BTCSignMessage 

func (device *Device) BTCSignMessage(
	coin messages.BTCCoin,
	scriptConfig *messages.BTCScriptConfigWithKeypath,
	message []byte,
) (*BTCSignMessageResult, error)

BTCSignMessage signs a Bitcoin message.

func (*Device) BTCXPub 

func (device *Device) BTCXPub(
	coin messages.BTCCoin,
	keypath []uint32,
	xpubType messages.BTCPubRequest_XPubType,
	display bool) (string, error)

BTCXPub queries the device for a btc, ltc, tbtc, tltc xpubs.

func (*Device) BluetoothToggleEnabled 

func (device *Device) BluetoothToggleEnabled() error

BluetoothToggleEnabled enables/disables Bluetooth.

func (*Device) BluetoothUpgrade 

func (device *Device) BluetoothUpgrade(firmware []byte) error

BluetoothUpgrade attempts an upgrade of the Bluetooth firmware.

func (*Device) CardanoAddress 

func (device *Device) CardanoAddress(
	network messages.CardanoNetwork,
	scriptConfig *messages.CardanoScriptConfig,
	display bool,
) (string, error)

CardanoAddress queries the device for a Cardano address.

func (*Device) CardanoSignTransaction 

func (device *Device) CardanoSignTransaction(
	transaction *messages.CardanoSignTransactionRequest,
) (*messages.CardanoSignTransactionResponse, error)

CardanoSignTransaction signs a Cardano transaction.

func (*Device) CardanoXPubs 

func (device *Device) CardanoXPubs(
	keypaths [][]uint32,
) ([][]byte, error)

CardanoXPubs queries the device for Cardano account xpubs.

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(
	chainID uint64,
	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(
	chainID uint64,
	keypath []uint32,
	nonce uint64,
	gasPrice *big.Int,
	gasLimit uint64,
	recipient [20]byte,
	value *big.Int,
	data []byte,
	recipientAddressCase messages.ETHAddressCase) ([]byte, error)

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

func (*Device) ETHSignEIP1559 

func (device *Device) ETHSignEIP1559(
	chainID uint64,
	keypath []uint32,
	nonce uint64,
	maxPriorityFeePerGas *big.Int,
	maxFeePerGas *big.Int,
	gasLimit uint64,
	recipient [20]byte,
	value *big.Int,
	data []byte,
	recipientAddressCase messages.ETHAddressCase) ([]byte, error)

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

func (*Device) ETHSignMessage 

func (device *Device) ETHSignMessage(
	chainID uint64,
	keypath []uint32,
	msg []byte,
) ([]byte, error)

ETHSignMessage signs an Ethereum message. The provided msg will be prefixed with "\x19Ethereum Signed Message\n" + len(msg) in the hardware, e.g. "\x19Ethereum Signed dMessage\n5hello" (yes, the len prefix is the ascii representation with no fixed size or delimiter, WTF). 27 is added to the recID to denote an uncompressed pubkey.

func (*Device) ETHSignTypedMessage 

func (device *Device) ETHSignTypedMessage(
	chainID uint64,
	keypath []uint32,
	jsonMsg []byte,
) ([]byte, error)

ETHSignTypedMessage signs an Ethereum EIP-712 typed message. 27 is added to the recID to denote an uncompressed pubkey.

func (*Device) GotoStartupSettings 

func (device *Device) GotoStartupSettings() error

GotoStartupSettings reboots into the bootloader with a 'Go to startup settings?' confirmation dialog.

func (*Device) Init 

func (device *Device) Init() error

Init initializes the device. It changes the status to StatusRequireAppUpgrade if needed, otherwise performs the attestation check, unlock, and noise pairing. This call is blocking. After this call finishes, Status() will be either: - StatusRequireAppUpgrade - StatusPairingFailed: pairing rejected on the device - StatusUnpaired: the host needs to confirm the pairing with ChannelHashVerify(true).

func (*Device) InsertSDCard 

func (device *Device) InsertSDCard() error

InsertSDCard sends a command to the device to prompt to insert the sd card.

func (*Device) ListBackups 

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

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

func (*Device) Product 

func (device *Device) Product() common.Product

Product returns the device product.

func (*Device) Reset 

func (device *Device) Reset() error

Reset factory resets the device. The device will reobot. You must not use this instance anymore afterwards.

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) RootFingerprint 

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

RootFingerprint returns the keystore's root fingerprint, which is the first 32 bits of the hash160 of the pubkey at the keypath m/.

https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#key-identifiers

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(Event, interface{}))

SetOnEvent installs the callback which will be called with various events.

func (*Device) SetPassword 

func (device *Device) SetPassword(seedLen int) error

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

`seed_len` must be exactly 16 or 32, creating a 16-byte or a 32-byte seed, corresponding to 12 resp. 24 BIP39 recovery words.

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) SupportsBluetooth 

func (device *Device) SupportsBluetooth() bool

SupportsBluetooth returns true if this device supports Bluetooth.

func (*Device) SupportsERC20 

func (device *Device) SupportsERC20(contractAddress string) bool

SupportsERC20 returns true if an ERC20 token is supported by the device api.

For now, this list only contains tokens relevant to the BitBoxApp, otherwise the bitbox02-api-js library size would blow up. TODO: move this to the bitbox-wallet-app repo.

func (*Device) SupportsETH 

func (device *Device) SupportsETH(chainID uint64) bool

SupportsETH returns true if ETH is supported by the device api.

func (*Device) SupportsLTC 

func (device *Device) SupportsLTC() bool

SupportsLTC returns true if LTC is supported by the device api.

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"`
	// This information is only available since firmwae v9.6.0. Will be an empty string for older
	// firmware versions.
	SecurechipModel string `json:"securechipModel"`
	// Available on Bluetooth-enabled devices, Will be `nil` otherwise.
	Bluetooth *BluetoothInfo `json:"bluetooth"`
}

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

type DeviceOption 

type DeviceOption func(*deviceOptions)

DeviceOption provides functional options.

func WithOptionalNoisePairingConfirmation 

func WithOptionalNoisePairingConfirmation(optional bool) DeviceOption

WithOptionalNoisePairingConfirmation allows the host to communicate over the encrypted noise channel without requiring a pairing confirmation on the BitBox.

SECURITY NOTE: this enables a MITM in the noise channel to go undetected. Use only if the noise channel is wrapped in another secure transport layer, e.g. a paired Bluetooth connection.

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 Event 

type Event string

Event instances are sent to the onEvent callback. 

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

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

	// EventAttestationCheckDone is fired when the attestation signature check is completed. In
	// case of failure, the user should be alerted, before they enter the password.
	EventAttestationCheckDone Event = "attestationCheckDone"
)

type Logger 

type Logger interface {
	// err can be nil
	Error(msg string, err error)
	Info(msg string)
	Debug(msg string)
}

Logger lets the library client provide their own logging infrastructure.

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 initialized).
	StatusConnected Status = "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"
)

type UnsupportedError 

type UnsupportedError string

UnsupportedError should wrap a version string, e.g. "9.2.0". It means a feature is not available before this version.

func (UnsupportedError) Error 

func (e UnsupportedError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package mocks contains the mock implementations to be used in testing.
 Package mocks contains the mock implementations to be used in testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.