Documentation ¶
Overview ¶
Package firmware contains the API to the physical device.
Index ¶
- Constants
- func BTCSignNeedsPrevTxs(scriptConfigs []*messages.BTCScriptConfigWithKeypath) bool
- func IsErrorAbort(err error) bool
- func NewBTCScriptConfigMultisig(threshold uint32, xpubs []string, ourXPubIndex uint32) (*messages.BTCScriptConfig, error)
- func NewBTCScriptConfigSimple(typ messages.BTCScriptConfig_SimpleType) *messages.BTCScriptConfig
- func NewXPub(xpub string) (*messages.XPub, error)
- type BTCPrevTx
- type BTCTx
- type BTCTxInput
- type Backup
- type Communication
- type ConfigInterface
- type Device
- func (device *Device) Attestation() *bool
- func (device *Device) BIP85AppBip39() error
- func (device *Device) BIP85AppLN() ([]byte, error)
- func (device *Device) BTCAddress(coin messages.BTCCoin, keypath []uint32, ...) (string, error)
- func (device *Device) BTCIsScriptConfigRegistered(coin messages.BTCCoin, scriptConfig *messages.BTCScriptConfig, ...) (bool, error)
- func (device *Device) BTCRegisterScriptConfig(coin messages.BTCCoin, scriptConfig *messages.BTCScriptConfig, ...) error
- func (device *Device) BTCSign(coin messages.BTCCoin, scriptConfigs []*messages.BTCScriptConfigWithKeypath, ...) ([][]byte, error)
- func (device *Device) BTCSignMessage(coin messages.BTCCoin, scriptConfig *messages.BTCScriptConfigWithKeypath, ...) (raw []byte, recID byte, electrum65 []byte, err error)
- func (device *Device) BTCXPub(coin messages.BTCCoin, keypath []uint32, ...) (string, error)
- func (device *Device) CardanoAddress(network messages.CardanoNetwork, scriptConfig *messages.CardanoScriptConfig, ...) (string, error)
- func (device *Device) CardanoSignTransaction(transaction *messages.CardanoSignTransactionRequest) (*messages.CardanoSignTransactionResponse, error)
- func (device *Device) CardanoXPubs(keypaths [][]uint32) ([][]byte, 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(chainID uint64, keypath []uint32, outputType messages.ETHPubRequest_OutputType, ...) (string, error)
- func (device *Device) ETHSign(chainID uint64, keypath []uint32, nonce uint64, gasPrice *big.Int, ...) ([]byte, error)
- func (device *Device) ETHSignEIP1559(chainID uint64, keypath []uint32, nonce uint64, maxPriorityFeePerGas *big.Int, ...) ([]byte, error)
- func (device *Device) ETHSignMessage(chainID uint64, keypath []uint32, msg []byte) ([]byte, error)
- func (device *Device) ETHSignTypedMessage(chainID uint64, keypath []uint32, jsonMsg []byte) ([]byte, error)
- func (device *Device) GotoStartupSettings() error
- func (device *Device) Init() error
- func (device *Device) InsertRemoveSDCard(action messages.InsertRemoveSDCardRequest_SDCardAction) error
- func (device *Device) ListBackups() ([]*Backup, error)
- func (device *Device) Product() common.Product
- func (device *Device) Reset() error
- func (device *Device) RestoreBackup(id string) error
- func (device *Device) RestoreFromMnemonic() error
- func (device *Device) RootFingerprint() ([]byte, error)
- func (device *Device) SetDeviceName(deviceName string) error
- func (device *Device) SetMnemonicPassphraseEnabled(enabled bool) error
- func (device *Device) SetOnEvent(onEvent func(Event, interface{}))
- func (device *Device) SetPassword(seedLen int) error
- func (device *Device) ShowMnemonic() error
- func (device *Device) Status() Status
- func (device *Device) SupportsERC20(contractAddress string) bool
- func (device *Device) SupportsETH(chainID uint64) bool
- func (device *Device) SupportsLTC() bool
- func (device *Device) UpgradeFirmware() error
- func (device *Device) Version() *semver.SemVer
- type DeviceInfo
- type Error
- type Event
- type Logger
- type Status
- type UnsupportedError
Constants ¶
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 IsErrorAbort ¶
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 NewBTCScriptConfigSimple ¶
func NewBTCScriptConfigSimple(typ messages.BTCScriptConfig_SimpleType) *messages.BTCScriptConfig
NewBTCScriptConfigSimple is a helper to construct the correct script config for simple script types.
Types ¶
type BTCPrevTx ¶
type BTCPrevTx struct { Version uint32 Inputs []*messages.BTCPrevTxInputRequest Outputs []*messages.BTCPrevTxOutputRequest Locktime uint32 }
BTCPrevTx is the transaction referenced by an input.
type BTCTx ¶
type BTCTx struct { Version uint32 Inputs []*BTCTxInput Outputs []*messages.BTCSignOutputRequest Locktime uint32 }
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 }
BTCTxInput contains the data needed to sign an input.
type Communication ¶
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, ) *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 ¶
Attestation returns the result of the automatic attestation check. If nil, the check has not been completed yet.
func (*Device) BIP85AppBip39 ¶
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 ¶
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, tx *BTCTx, formatUnit messages.BTCSignInitRequest_FormatUnit, ) ([][]byte, error)
BTCSign signs a bitcoin or bitcoin-like transaction. The previous transactions of the inputs need to be provided if `BTCSignNeedsPrevTxs()` returns true.
Returns one 64 byte signature per input.
func (*Device) BTCSignMessage ¶
func (device *Device) BTCSignMessage( coin messages.BTCCoin, scriptConfig *messages.BTCScriptConfigWithKeypath, message []byte, ) (raw []byte, recID byte, electrum65 []byte, err error)
BTCSignMessage signs a Bitcoin message. The 64 byte raw signature, the recoverable ID and the 65 byte signature in Electrum format are returned.
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) 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 ¶
CardanoXPubs queries the device for Cardano account xpubs.
func (*Device) ChannelHash ¶
ChannelHash returns the hashed handshake channel binding.
func (*Device) ChannelHashVerify ¶
ChannelHashVerify verifies the ChannelHash.
func (*Device) CheckBackup ¶
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 ¶
CheckSDCard checks whether an sd card is inserted in the device.
func (*Device) CreateBackup ¶
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) ([]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) ([]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 message\n" + len(msg) in the hardware, e.g. "\x19Ethereum\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 ¶
GotoStartupSettings reboots into the bootloader with a 'Go to startup settings?' confirmation dialog.
func (*Device) Init ¶
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) 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) ListBackups ¶
ListBackups returns a list of all backups on the SD card.
func (*Device) RestoreBackup ¶
RestoreBackup restores a backup returned by ListBackups (id).
func (*Device) RestoreFromMnemonic ¶
RestoreFromMnemonic invokes the mnemonic phrase import workflow.
func (*Device) RootFingerprint ¶
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 ¶
SetDeviceName sends a request to the device using protobuf to set the device name.
func (*Device) SetMnemonicPassphraseEnabled ¶
SetMnemonicPassphraseEnabled enables or disables entering a mnemonic passphrase after the normal unlock.
func (*Device) SetOnEvent ¶
SetOnEvent installs the callback which will be called with various events.
func (*Device) SetPassword ¶
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 ¶
ShowMnemonic lets the user export the bip39 mnemonic phrase on the device.
func (*Device) SupportsERC20 ¶
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 ¶
SupportsETH returns true if ETH is supported by the device api.
func (*Device) SupportsLTC ¶
SupportsLTC returns true if LTC is supported by the device api.
func (*Device) UpgradeFirmware ¶
UpgradeFirmware reboots into the bootloader so a firmware can be flashed.
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"` }
DeviceInfo is the data returned from the device info api call.
type Error ¶
Error wraps an error from bitbox02.
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