org.bitcoinj.wallet

Class BasicKeyChain

java.lang.Object

org.bitcoinj.wallet.BasicKeyChain

All Implemented Interfaces:

EncryptableKeyChain, KeyChain

public class BasicKeyChain
extends java.lang.Object
implements EncryptableKeyChain

A KeyChain that implements the simplest model possible: it can have keys imported into it, and just acts as a dumb bag of keys. It will, left to its own devices, always return the same key for usage by the wallet, although it will automatically add one to itself if it's empty or if encryption is requested.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BasicKeyChain.State Whether this basic key chain is empty, full of regular (usable for signing) keys, or full of watching keys.

Nested classes/interfaces inherited from interface org.bitcoinj.wallet.KeyChain

KeyChain.KeyPurpose

Constructor Summary

Constructors

Constructor and Description
BasicKeyChain()
BasicKeyChain(KeyCrypter crypter)

Method Summary

Modifier and Type	Method and Description
void	addEventListener(KeyChainEventListener listener) Adds a listener for events that are run when keys are added, on the user thread.
void	addEventListener(KeyChainEventListener listener, java.util.concurrent.Executor executor) Adds a listener for events that are run when keys are added, on the given executor.
boolean	checkAESKey(org.bouncycastle.crypto.params.KeyParameter aesKey) Check whether the AES key can decrypt the first encrypted key in the wallet.
boolean	checkPassword(java.lang.CharSequence password) Returns whether the given password is correct for this key chain.
ECKey	findKeyFromPubHash(byte[] pubKeyHash)
ECKey	findKeyFromPubKey(byte[] pubKey)
java.util.List<ECKey>	findKeysBefore(long timeSecs) Returns a list of all ECKeys created after the given UNIX time.
ECKey	findOldestKeyAfter(long timeSecs) Returns the first ECKey created after the given UNIX time, or null if there is none.
static BasicKeyChain	fromProtobufEncrypted(java.util.List<Protos.Key> keys, KeyCrypter crypter) Returns a new BasicKeyChain that contains all basic, ORIGINAL type keys and also any encrypted keys extracted from the list.
static BasicKeyChain	fromProtobufUnencrypted(java.util.List<Protos.Key> keys) Returns a new BasicKeyChain that contains all basic, ORIGINAL type keys extracted from the list.
long	getEarliestKeyCreationTime() Returns the earliest creation time of keys in this chain, in seconds since the epoch.
BloomFilter	getFilter(int size, double falsePositiveRate, long tweak) Gets a bloom filter that contains all of the public keys from this chain, and which will provide the given false-positive rate if it has size elements.
ECKey	getKey(KeyChain.KeyPurpose ignored) Obtains a key intended for the given purpose.
KeyCrypter	getKeyCrypter() Returns the KeyCrypter in use or null if the key chain is not encrypted.
java.util.List<ECKey>	getKeys() Returns a copy of the list of keys that this chain is managing.
java.util.List<ECKey>	getKeys(KeyChain.KeyPurpose purpose, int numberOfKeys) Obtains a number of key/s intended for the given purpose.
java.util.List<ListenerRegistration<KeyChainEventListener>>	getListeners()
boolean	hasKey(ECKey key) Returns true if the given key is in the chain.
void	importKey(ECKey key) Imports a key to the key chain.
int	importKeys(ECKey... keys)
int	importKeys(java.util.List<? extends ECKey> keys)
BasicKeyChain.State	isWatching() Returns whether this chain consists of pubkey only (watching) keys, regular keys (usable for signing), or has no keys in it yet at all (thus we cannot tell).
int	numBloomFilterEntries() Returns the number of elements this chain wishes to insert into the Bloom filter.
int	numKeys() Returns the number of keys this key chain manages.
boolean	removeEventListener(KeyChainEventListener listener) Removes a listener for events that are run when keys are added.
boolean	removeKey(ECKey key) Removes the given key from the keychain.
java.util.List<Protos.Key>	serializeToProtobuf() Returns a list of keys serialized to the bitcoinj protobuf format.
BasicKeyChain	toDecrypted(java.lang.CharSequence password) Decrypts the key chain with the given password.
BasicKeyChain	toDecrypted(org.bouncycastle.crypto.params.KeyParameter aesKey) Decrypt the key chain with the given AES key and whatever KeyCrypter is already set.
BasicKeyChain	toEncrypted(java.lang.CharSequence password) Convenience wrapper around toEncrypted(KeyCrypter, org.bouncycastle.crypto.params.KeyParameter) which uses the default Scrypt key derivation algorithm and parameters, derives a key from the given password and returns the created key.
BasicKeyChain	toEncrypted(KeyCrypter keyCrypter, org.bouncycastle.crypto.params.KeyParameter aesKey) Encrypt the wallet using the KeyCrypter and the AES key.
java.lang.String	toString(boolean includePrivateKeys, org.bouncycastle.crypto.params.KeyParameter aesKey, NetworkParameters params)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicKeyChain

public BasicKeyChain()

BasicKeyChain

public BasicKeyChain(@Nullable
                     KeyCrypter crypter)

Method Detail

getKeyCrypter

@Nullable
public KeyCrypter getKeyCrypter()

Returns the KeyCrypter in use or null if the key chain is not encrypted.

Specified by:

getKeyCrypter in interface EncryptableKeyChain

getKey

public ECKey getKey(@Nullable
                    KeyChain.KeyPurpose ignored)

Description copied from interface: KeyChain

Obtains a key intended for the given purpose. The chain may create a new key, derive one, or re-use an old one.

Specified by:

getKey in interface KeyChain

getKeys

public java.util.List<ECKey> getKeys(@Nullable
                                     KeyChain.KeyPurpose purpose,
                                     int numberOfKeys)

Description copied from interface: KeyChain

Obtains a number of key/s intended for the given purpose. The chain may create new key/s, derive, or re-use an old one.

Specified by:

getKeys in interface KeyChain

getKeys

public java.util.List<ECKey> getKeys()

Returns a copy of the list of keys that this chain is managing.

importKeys

public int importKeys(ECKey... keys)

importKeys

public int importKeys(java.util.List<? extends ECKey> keys)

importKey

public void importKey(ECKey key)

Imports a key to the key chain. If key is present in the key chain, ignore it.

findKeyFromPubHash

public ECKey findKeyFromPubHash(byte[] pubKeyHash)

findKeyFromPubKey

public ECKey findKeyFromPubKey(byte[] pubKey)

hasKey

public boolean hasKey(ECKey key)

Description copied from interface: KeyChain

Returns true if the given key is in the chain.

Specified by:

hasKey in interface KeyChain

numKeys

public int numKeys()

Description copied from interface: KeyChain

Returns the number of keys this key chain manages.

Specified by:

numKeys in interface KeyChain

isWatching

public BasicKeyChain.State isWatching()

Returns whether this chain consists of pubkey only (watching) keys, regular keys (usable for signing), or has no keys in it yet at all (thus we cannot tell).

removeKey

public boolean removeKey(ECKey key)

Removes the given key from the keychain. Be very careful with this - losing a private key destroys the money associated with it.

Returns:

Whether the key was removed or not.

getEarliestKeyCreationTime

public long getEarliestKeyCreationTime()

Description copied from interface: KeyChain

Returns the earliest creation time of keys in this chain, in seconds since the epoch. This can return zero if at least one key does not have that data (was created before key timestamping was implemented). If there are no keys in the wallet, Long.MAX_VALUE is returned.

Specified by:

getEarliestKeyCreationTime in interface KeyChain

getListeners

public java.util.List<ListenerRegistration<KeyChainEventListener>> getListeners()

serializeToProtobuf

public java.util.List<Protos.Key> serializeToProtobuf()

Description copied from interface: KeyChain

Returns a list of keys serialized to the bitcoinj protobuf format.

Specified by:

serializeToProtobuf in interface KeyChain

fromProtobufUnencrypted

public static BasicKeyChain fromProtobufUnencrypted(java.util.List<Protos.Key> keys)
                                             throws UnreadableWalletException

Returns a new BasicKeyChain that contains all basic, ORIGINAL type keys extracted from the list. Unrecognised key types are ignored.

Throws:

UnreadableWalletException

fromProtobufEncrypted

public static BasicKeyChain fromProtobufEncrypted(java.util.List<Protos.Key> keys,
                                                  KeyCrypter crypter)
                                           throws UnreadableWalletException

Returns a new BasicKeyChain that contains all basic, ORIGINAL type keys and also any encrypted keys extracted from the list. Unrecognised key types are ignored.

Throws:

UnreadableWalletException.BadPassword - if the password doesn't seem to match

UnreadableWalletException - if the data structures are corrupted/inconsistent

addEventListener

public void addEventListener(KeyChainEventListener listener)

Description copied from interface: KeyChain

Adds a listener for events that are run when keys are added, on the user thread.

Specified by:

addEventListener in interface KeyChain

addEventListener

public void addEventListener(KeyChainEventListener listener,
                             java.util.concurrent.Executor executor)

Description copied from interface: KeyChain

Adds a listener for events that are run when keys are added, on the given executor.

Specified by:

addEventListener in interface KeyChain

removeEventListener

public boolean removeEventListener(KeyChainEventListener listener)

Description copied from interface: KeyChain

Removes a listener for events that are run when keys are added.

Specified by:

removeEventListener in interface KeyChain

toEncrypted

public BasicKeyChain toEncrypted(java.lang.CharSequence password)

Convenience wrapper around toEncrypted(KeyCrypter, org.bouncycastle.crypto.params.KeyParameter) which uses the default Scrypt key derivation algorithm and parameters, derives a key from the given password and returns the created key.

Specified by:

toEncrypted in interface EncryptableKeyChain

Returns:

The derived key, in case you wish to cache it for future use.

toEncrypted

public BasicKeyChain toEncrypted(KeyCrypter keyCrypter,
                                 org.bouncycastle.crypto.params.KeyParameter aesKey)

Encrypt the wallet using the KeyCrypter and the AES key. A good default KeyCrypter to use is KeyCrypterScrypt.

Specified by:

toEncrypted in interface EncryptableKeyChain

Parameters:

keyCrypter - The KeyCrypter that specifies how to encrypt/ decrypt a key

aesKey - AES key to use (normally created using KeyCrypter#deriveKey and cached as it is time consuming to create from a password)

Throws:

KeyCrypterException - Thrown if the wallet encryption fails. If so, the wallet state is unchanged.

toDecrypted

public BasicKeyChain toDecrypted(java.lang.CharSequence password)

Description copied from interface: EncryptableKeyChain

Decrypts the key chain with the given password. See EncryptableKeyChain.toDecrypted(KeyParameter) for details.

Specified by:

toDecrypted in interface EncryptableKeyChain

toDecrypted

public BasicKeyChain toDecrypted(org.bouncycastle.crypto.params.KeyParameter aesKey)

Description copied from interface: EncryptableKeyChain

Decrypt the key chain with the given AES key and whatever KeyCrypter is already set. Note that if you just want to spend money from an encrypted wallet, don't decrypt the whole thing first. Instead, set the SendRequest.aesKey field before asking the wallet to build the send.

Specified by:

toDecrypted in interface EncryptableKeyChain

Parameters:

aesKey - AES key to use (normally created using KeyCrypter#deriveKey and cached as it is time consuming to create from a password)

checkPassword

public boolean checkPassword(java.lang.CharSequence password)

Returns whether the given password is correct for this key chain.

Specified by:

checkPassword in interface EncryptableKeyChain

Throws:

java.lang.IllegalStateException - if the chain is not encrypted at all.

checkAESKey

public boolean checkAESKey(org.bouncycastle.crypto.params.KeyParameter aesKey)

Check whether the AES key can decrypt the first encrypted key in the wallet.

Specified by:

checkAESKey in interface EncryptableKeyChain

Returns:

true if AES key supplied can decrypt the first encrypted private key in the wallet, false otherwise.

getFilter

public BloomFilter getFilter(int size,
                             double falsePositiveRate,
                             long tweak)

Description copied from interface: KeyChain

Gets a bloom filter that contains all of the public keys from this chain, and which will provide the given false-positive rate if it has size elements. Keep in mind that you will get 2 elements in the bloom filter for each key in the key chain, for the public key and the hash of the public key (address form). For this reason size should be at least 2x the result of KeyChain.numKeys().

This is used to generate a BloomFilter which can be BloomFilter.merge(BloomFilter)d with another. It could also be used if you have a specific target for the filter's size.

See the docs for BloomFilter.BloomFilter(int, double, long) for a brief explanation of anonymity when using bloom filters, and for the meaning of these parameters.

Specified by:

getFilter in interface KeyChain

numBloomFilterEntries

public int numBloomFilterEntries()

Description copied from interface: KeyChain

Returns the number of elements this chain wishes to insert into the Bloom filter. The size passed to KeyChain.getFilter(int, double, long) should be at least this large.

Specified by:

numBloomFilterEntries in interface KeyChain

findOldestKeyAfter

@Nullable
public ECKey findOldestKeyAfter(long timeSecs)

Returns the first ECKey created after the given UNIX time, or null if there is none.

findKeysBefore

public java.util.List<ECKey> findKeysBefore(long timeSecs)

Returns a list of all ECKeys created after the given UNIX time.

toString

public java.lang.String toString(boolean includePrivateKeys,
                                 @Nullable
                                 org.bouncycastle.crypto.params.KeyParameter aesKey,
                                 NetworkParameters params)