public class HardwareWalletService extends Object
Service to provide the following to application:
Refer to the examples for how to correctly configure the service for use in downstream consumer applications.
Constructor and Description |
---|
HardwareWalletService(HardwareWalletClient client) |
Modifier and Type | Method and Description |
---|---|
void |
changePIN(boolean remove)
Change or remove the device PIN.
|
void |
encryptMessage(byte[] message)
Request that the device encrypts the given message.
|
byte[] |
generateEntropy() |
HardwareWalletContext |
getContext() |
boolean |
isDeviceReady() |
boolean |
isStopped() |
boolean |
isWalletPresent() |
void |
loadWallet(String language,
String label,
String seedPhrase,
String pin)
Initiate the process where the hardware wallet is first wiped then loaded using an external seed phrase
|
void |
provideEntropy(byte[] entropy)
Provide additional entropy to the device to reduce risk of hardware compromise
|
void |
providePIN(String pin)
Provide the user entered PIN
|
void |
requestAddress(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
boolean showDisplay)
Request an address from the device.
|
void |
requestCancel()
Cancel the current operation and return to the initialised state
|
void |
requestCipherKey(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
byte[] displayText,
byte[] keyValue,
boolean isEncrypting,
boolean askOnDecrypt,
boolean askOnEncrypt)
Request some data to be encrypted or decrypted using an address key from the device.
|
void |
requestDeterministicHierarchy(List<org.bitcoinj.crypto.ChildNumber> childNumbers)
Request a deterministic hierarchy based on the given child numbers.
|
void |
requestPing()
Ping the device
|
void |
requestPublicKey(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index)
Request a public key from the device.
|
void |
secureCreateWallet(String language,
String label,
boolean displayRandom,
boolean pinProtection,
int strength)
Initiate the process where the hardware wallet is first wiped then reset using its own entropy
|
void |
signMessage(int account,
org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose,
int index,
byte[] message)
Request some data to be signed using an address key from the device.
|
void |
signTx(org.bitcoinj.core.Transaction transaction,
Map<Integer,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> receivingAddressPathMap,
Map<org.bitcoinj.core.Address,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> changeAddressPathMap)
Request that the device signs the given transaction (unlimited number of inputs/outputs).
|
void |
simpleSignTx(org.bitcoinj.core.Transaction transaction,
Map<Integer,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> receivingAddressPathMap,
Map<org.bitcoinj.core.Address,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> changeAddressPathMap)
Request that the device signs the given transaction (limited number of inputs/outputs).
|
void |
start()
Start the service and await the connection of a hardware wallet
|
void |
stopAndWait()
Stop the service
|
void |
wipeDevice()
Clear the device back to factory settings
|
public HardwareWalletService(HardwareWalletClient client)
client
- The hardware wallet client providing the low level messagespublic void start()
Start the service and await the connection of a hardware wallet
public void stopAndWait()
Stop the service
public boolean isStopped()
public HardwareWalletContext getContext()
public boolean isDeviceReady()
public boolean isWalletPresent()
Features.isInitialised()
)IllegalStateException
- If called when the device is not ready (see isDeviceReady()
)public void requestPing()
Ping the device
This will trigger a SHOW_OPERATION_SUCCEEDED
public void requestCancel()
Cancel the current operation and return to the initialised state
This will trigger a SHOW_OPERATION_FAILED and a DEVICE_READY event during the reset phase
public void wipeDevice()
Clear the device back to factory settings
public void changePIN(boolean remove)
Change or remove the device PIN.
remove
- True if an existing PIN should be removedpublic void secureCreateWallet(String language, String label, boolean displayRandom, boolean pinProtection, int strength)
Initiate the process where the hardware wallet is first wiped then reset using its own entropy
This is the recommended method to use for creating a wallet securely.
language
- The language (e.g. "english")label
- The label to display below the logo (e.g "Fred")displayRandom
- True if the device should display the entropy generated by the device before asking for additional entropypinProtection
- True if the device should use PIN protectionstrength
- The number of bits in the seed phrase (128 bits = 12 words, 196 bits = 18 words, 256 bits = 24 words)public void loadWallet(String language, String label, String seedPhrase, String pin)
Initiate the process where the hardware wallet is first wiped then loaded using an external seed phrase
language
- The language (e.g. "english")label
- The label to display below the logo (e.g "Fred")seedPhrase
- The seed phrase provided by the user in the clearpin
- The personal identification number (PIN) in the clearpublic void providePIN(String pin)
Provide the user entered PIN
pin
- The PIN taken from the user ideally through an obfuscated PIN matrix approachpublic void provideEntropy(byte[] entropy)
Provide additional entropy to the device to reduce risk of hardware compromise
entropy
- Random bytes provided by a secure random number generator (see generateEntropy()
public void requestAddress(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, boolean showDisplay)
Request an address from the device. The device will respond by providing an address calculated based on the BIP-44 deterministic wallet approach from the master node.
The BIP-44 chain code is arranged as follows:
M/44'/coin type'/account'/key purpose/index
Notes:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addressshowDisplay
- True if the device should display the same address to allow the user to verify no tampering has occurred (recommended).public void requestPublicKey(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index)
Request a public key from the device. The device will respond by providing the public key calculated based on the BIP-44 deterministic wallet approach from the master node.
The BIP-44 chain code is arranged as follows:
M/44'/coin type'/account'/key purpose/index
Notes:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addresspublic void requestDeterministicHierarchy(List<org.bitcoinj.crypto.ChildNumber> childNumbers)
Request a deterministic hierarchy based on the given child numbers.
This can be used to create a "watching wallet" that does not contain any private keys so long as all hardened child numbers are included.
childNumbers
- The list of child numbers representing a path that may include hardened entriespublic void requestCipherKey(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, byte[] displayText, byte[] keyValue, boolean isEncrypting, boolean askOnDecrypt, boolean askOnEncrypt)
Request some data to be encrypted or decrypted using an address key from the device. The device will respond by providing the encrypted/decrypted data based on the key derived using the BIP-44 deterministic wallet approach from the master node. This data is unique to the seed phrase and is deterministic.
The BIP-44 chain code is arranged as follows:
M/44'/coin type'/account'/key purpose/index
Notes:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addressdisplayText
- The cipher key shown to the user (e.g. "User message")keyValue
- The key value (e.g. "[16 bytes of random data]")isEncrypting
- True if encryptingaskOnDecrypt
- True if device should ask on decryptingaskOnEncrypt
- True if device should ask on encryptingpublic void signMessage(int account, org.bitcoinj.wallet.KeyChain.KeyPurpose keyPurpose, int index, byte[] message)
Request some data to be signed using an address key from the device. The device will respond by providing the signed data based on the key derived using the BIP-44 deterministic wallet approach from the master node.
The BIP-44 chain code is arranged as follows:
M/44'/coin type'/account'/key purpose/index
Notes:
account
- The plain account number (0 gives maximum compatibility)keyPurpose
- The key purpose (RECEIVE_FUNDS,CHANGE,REFUND,AUTHENTICATION etc)index
- The plain index of the required addressmessage
- The message for signingpublic void simpleSignTx(org.bitcoinj.core.Transaction transaction, Map<Integer,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> receivingAddressPathMap, Map<org.bitcoinj.core.Address,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> changeAddressPathMap)
Request that the device signs the given transaction (limited number of inputs/outputs).
transaction
- The transaction containing all the inputs and outputsreceivingAddressPathMap
- The paths to the receiving addresses for this transaction keyed by input indexchangeAddressPathMap
- The paths to the change address for this transaction keyed by Addresspublic void signTx(org.bitcoinj.core.Transaction transaction, Map<Integer,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> receivingAddressPathMap, Map<org.bitcoinj.core.Address,com.google.common.collect.ImmutableList<org.bitcoinj.crypto.ChildNumber>> changeAddressPathMap)
Request that the device signs the given transaction (unlimited number of inputs/outputs).
transaction
- The transaction containing all the inputs and outputsreceivingAddressPathMap
- The paths to the receiving addresses for this transaction keyed by input indexchangeAddressPathMap
- The paths to the change address for this transaction keyed by Addresspublic void encryptMessage(byte[] message)
Request that the device encrypts the given message.
message
- The message for signingpublic byte[] generateEntropy()
Copyright © 2013–2018 Bitcoin Solutions Ltd. All rights reserved.