org.bitcoinj.crypto

Class DeterministicKey

java.lang.Object

org.bitcoinj.core.ECKey

org.bitcoinj.crypto.DeterministicKey

All Implemented Interfaces:

EncryptableItem

public class DeterministicKey
extends ECKey

A deterministic key is a node in a DeterministicHierarchy. As per the BIP 32 specification it is a pair (key, chaincode). If you know its path in the tree and its chain code you can derive more keys from this. To obtain one of these, you can call HDKeyDerivation.createMasterPrivateKey(byte[]).

Nested Class Summary

Nested classes/interfaces inherited from class org.bitcoinj.core.ECKey

ECKey.ECDSASignature, ECKey.KeyIsEncryptedException, ECKey.MissingPrivateKeyException

Field Summary

Fields

Modifier and Type	Field and Description
static Comparator<ECKey>	CHILDNUM_ORDER Sorts deterministic keys in the order of their child number.

Fields inherited from class org.bitcoinj.core.ECKey

AGE_COMPARATOR, creationTimeSeconds, CURVE, encryptedPrivateKey, FAKE_SIGNATURES, HALF_CURVE_ORDER, keyCrypter, priv, pub, PUBKEY_COMPARATOR

Constructor Summary

Constructors

Constructor and Description
DeterministicKey(DeterministicKey keyToClone, DeterministicKey newParent) Clones the key
DeterministicKey(ImmutableList<ChildNumber> childNumberPath, byte[] chainCode, BigInteger priv, DeterministicKey parent) Constructs a key from its components.
DeterministicKey(ImmutableList<ChildNumber> childNumberPath, byte[] chainCode, org.spongycastle.math.ec.ECPoint publicAsPoint, BigInteger priv, DeterministicKey parent)
DeterministicKey(ImmutableList<ChildNumber> childNumberPath, byte[] chainCode, KeyCrypter crypter, LazyECPoint pub, EncryptedData priv, DeterministicKey parent) Constructs a key from its components.
DeterministicKey(ImmutableList<ChildNumber> childNumberPath, byte[] chainCode, LazyECPoint publicAsPoint, BigInteger priv, DeterministicKey parent) Constructs a key from its components.

Method Summary

Modifier and Type	Method and Description
DeterministicKey	decrypt(KeyCrypter keyCrypter, org.spongycastle.crypto.params.KeyParameter aesKey) Create a decrypted private key with the keyCrypter and AES key supplied.
DeterministicKey	decrypt(org.spongycastle.crypto.params.KeyParameter aesKey) Create a decrypted private key with AES key.
DeterministicKey	derive(int child) Derives a child at the given index using hardened derivation.
static DeterministicKey	deserialize(NetworkParameters params, byte[] serializedKey) Deserialize an HD Key with no parent
static DeterministicKey	deserialize(NetworkParameters params, byte[] serializedKey, DeterministicKey parent) Deserialize an HD Key.
static DeterministicKey	deserializeB58(DeterministicKey parent, String base58, NetworkParameters params) Deserialize a base-58-encoded HD Key.
static DeterministicKey	deserializeB58(String base58, NetworkParameters params) Deserialize a base-58-encoded HD Key with no parent
DeterministicKey	dropParent() Returns the same key with the parent pointer removed (it still knows its own path and the parent fingerprint).
DeterministicKey	dropPrivateBytes() Returns the same key with the private bytes removed.
DeterministicKey	encrypt(KeyCrypter keyCrypter, org.spongycastle.crypto.params.KeyParameter aesKey) Create an encrypted private key with the keyCrypter and the AES key supplied.
DeterministicKey	encrypt(KeyCrypter keyCrypter, org.spongycastle.crypto.params.KeyParameter aesKey, DeterministicKey newParent)
boolean	equals(Object o) Verifies equality of all fields but NOT the parent pointer (thus the same key derived in two separate heirarchy objects will equal each other.
void	formatKeyWithAddress(boolean includePrivateKeys, StringBuilder builder, NetworkParameters params)
byte[]	getChainCode() Returns the chain code associated with this key.
ChildNumber	getChildNumber() Returns the last element of the path returned by getPath()
long	getCreationTimeSeconds() The creation time of a deterministic key is equal to that of its parent, unless this key is the root of a tree in which case the time is stored alongside the key as per normal, see ECKey.getCreationTimeSeconds().
int	getDepth() Return this key's depth in the hierarchy, where the root node is at depth zero.
int	getFingerprint() Returns the first 32 bits of the result of getIdentifier().
byte[]	getIdentifier() Returns RIPE-MD160(SHA256(pub key bytes)).
KeyCrypter	getKeyCrypter() Returns this keys KeyCrypter or the keycrypter of its parent key.
DeterministicKey	getParent()
int	getParentFingerprint() Return the fingerprint of the key from which this key was derived, if this is a child key, or else an array of four zero-value bytes.
ImmutableList<ChildNumber>	getPath() Returns the path through some DeterministicHierarchy which reaches this keys position in the tree.
String	getPathAsString() Returns the path of this key as a human readable string starting with M to indicate the master key.
BigInteger	getPrivKey() Returns the private key of this deterministic key.
byte[]	getPrivKeyBytes33() Returns private key bytes, padded with zeros to 33 bytes.
byte[]	getSecretBytes() A wrapper for ECKey.getPrivKeyBytes() that returns null if the private key bytes are missing or would have to be derived (for the HD key case).
int	hashCode()
boolean	hasPrivKey() Returns true if this key has unencrypted access to private key bytes.
boolean	isEncrypted() A deterministic key is considered to be encrypted if it has access to encrypted private key bytes, OR if its parent does.
boolean	isPubKeyOnly() A deterministic key is considered to be 'public key only' if it hasn't got a private key part and it cannot be rederived.
byte[]	serializePrivate(NetworkParameters params)
String	serializePrivB58(NetworkParameters params)
String	serializePubB58(NetworkParameters params)
byte[]	serializePublic(NetworkParameters params)
void	setCreationTimeSeconds(long newCreationTimeSeconds) The creation time of a deterministic key is equal to that of its parent, unless this key is the root of a tree.
ECKey.ECDSASignature	sign(Sha256Hash input, org.spongycastle.crypto.params.KeyParameter aesKey) Signs the given hash and returns the R and S components as BigIntegers.
String	toString()

Methods inherited from class org.bitcoinj.core.ECKey

compressPoint, compressPoint, decompress, decompressPoint, decompressPoint, doSign, encryptionIsReversible, fromASN1, fromEncrypted, fromPrivate, fromPrivate, fromPrivate, fromPrivate, fromPrivateAndPrecalculatedPublic, fromPrivateAndPrecalculatedPublic, fromPublicOnly, fromPublicOnly, getEncryptedData, getEncryptedPrivateKey, getEncryptionType, getPrivateKeyAsHex, getPrivateKeyAsWiF, getPrivateKeyEncoded, getPrivKeyBytes, getPubKey, getPubKeyHash, getPubKeyPoint, getPublicKeyAsHex, isCompressed, isPubKeyCanonical, isWatching, maybeDecrypt, publicKeyFromPrivate, publicPointFromPrivate, recoverFromSignature, sign, signedMessageToKey, signMessage, signMessage, toAddress, toASN1, toStringWithPrivate, verify, verify, verify, verify, verifyMessage, verifyOrThrow, verifyOrThrow

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

CHILDNUM_ORDER

public static final Comparator<ECKey> CHILDNUM_ORDER

Sorts deterministic keys in the order of their child number. That's usually the order used to derive them.

Constructor Detail

DeterministicKey

public DeterministicKey(ImmutableList<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        LazyECPoint publicAsPoint,
                        @Nullable
                        BigInteger priv,
                        @Nullable
                        DeterministicKey parent)

Constructs a key from its components. This is not normally something you should use.

DeterministicKey

public DeterministicKey(ImmutableList<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        org.spongycastle.math.ec.ECPoint publicAsPoint,
                        @Nullable
                        BigInteger priv,
                        @Nullable
                        DeterministicKey parent)

DeterministicKey

public DeterministicKey(ImmutableList<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        BigInteger priv,
                        @Nullable
                        DeterministicKey parent)

Constructs a key from its components. This is not normally something you should use.

DeterministicKey

public DeterministicKey(ImmutableList<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        KeyCrypter crypter,
                        LazyECPoint pub,
                        EncryptedData priv,
                        @Nullable
                        DeterministicKey parent)

Constructs a key from its components. This is not normally something you should use.

DeterministicKey

public DeterministicKey(DeterministicKey keyToClone,
                        DeterministicKey newParent)

Clones the key

Method Detail

getPath

public ImmutableList<ChildNumber> getPath()

Returns the path through some DeterministicHierarchy which reaches this keys position in the tree. A path can be written as 1/2/1 which means the first child of the root, the second child of that node, then the first child of that node.

getPathAsString

public String getPathAsString()

Returns the path of this key as a human readable string starting with M to indicate the master key.

getDepth

public int getDepth()

Return this key's depth in the hierarchy, where the root node is at depth zero. This may be different than the number of segments in the path if this key was deserialized without access to its parent.

getChildNumber

public ChildNumber getChildNumber()

Returns the last element of the path returned by getPath()

getChainCode

public byte[] getChainCode()

Returns the chain code associated with this key. See the specification to learn more about chain codes.

getIdentifier

public byte[] getIdentifier()

Returns RIPE-MD160(SHA256(pub key bytes)).

getFingerprint

public int getFingerprint()

Returns the first 32 bits of the result of getIdentifier().

getParent

@Nullable
public DeterministicKey getParent()

getParentFingerprint

public int getParentFingerprint()

Return the fingerprint of the key from which this key was derived, if this is a child key, or else an array of four zero-value bytes.

getPrivKeyBytes33

public byte[] getPrivKeyBytes33()

Returns private key bytes, padded with zeros to 33 bytes.

Throws:

IllegalStateException - if the private key bytes are missing.

dropPrivateBytes

public DeterministicKey dropPrivateBytes()

Returns the same key with the private bytes removed. May return the same instance. The purpose of this is to save memory: the private key can always be very efficiently rederived from a parent that a private key, so storing all the private keys in RAM is a poor tradeoff especially on constrained devices. This means that the returned key may still be usable for signing and so on, so don't expect it to be a true pubkey-only object! If you want that then you should follow this call with a call to dropParent().

dropParent

public DeterministicKey dropParent()

Returns the same key with the parent pointer removed (it still knows its own path and the parent fingerprint).

If this key doesn't have private key bytes stored/cached itself, but could rederive them from the parent, then the new key returned by this method won't be able to do that. Thus, using dropPrivateBytes().dropParent() on a regular DeterministicKey will yield a new DeterministicKey that cannot sign or do other things involving the private key at all.

encrypt

public DeterministicKey encrypt(KeyCrypter keyCrypter,
                                org.spongycastle.crypto.params.KeyParameter aesKey)
                         throws KeyCrypterException

Description copied from class: ECKey

Create an encrypted private key with the keyCrypter and the AES key supplied. This method returns a new encrypted key and leaves the original unchanged.

Overrides:

encrypt in class ECKey

Parameters:

keyCrypter - The keyCrypter that specifies exactly how the encrypted bytes are created.

aesKey - The KeyParameter with the AES encryption key (usually constructed with keyCrypter#deriveKey and cached as it is slow to create).

Returns:

encryptedKey

Throws:

KeyCrypterException

encrypt

public DeterministicKey encrypt(KeyCrypter keyCrypter,
                                org.spongycastle.crypto.params.KeyParameter aesKey,
                                @Nullable
                                DeterministicKey newParent)
                         throws KeyCrypterException

Throws:

KeyCrypterException

isPubKeyOnly

public boolean isPubKeyOnly()

A deterministic key is considered to be 'public key only' if it hasn't got a private key part and it cannot be rederived. If the hierarchy is encrypted this returns true.

Overrides:

isPubKeyOnly in class ECKey

hasPrivKey

public boolean hasPrivKey()

Returns true if this key has unencrypted access to private key bytes. Does the opposite of ECKey.isPubKeyOnly().

Overrides:

hasPrivKey in class ECKey

getSecretBytes

@Nullable
public byte[] getSecretBytes()

Description copied from class: ECKey

A wrapper for ECKey.getPrivKeyBytes() that returns null if the private key bytes are missing or would have to be derived (for the HD key case).

Specified by:

getSecretBytes in interface EncryptableItem

Overrides:

getSecretBytes in class ECKey

isEncrypted

public boolean isEncrypted()

A deterministic key is considered to be encrypted if it has access to encrypted private key bytes, OR if its parent does. The reason is because the parent would be encrypted under the same key and this key knows how to rederive its own private key bytes from the parent, if needed.

Specified by:

isEncrypted in interface EncryptableItem

Overrides:

isEncrypted in class ECKey

getKeyCrypter

@Nullable
public KeyCrypter getKeyCrypter()

Returns this keys KeyCrypter or the keycrypter of its parent key.

Overrides:

getKeyCrypter in class ECKey

sign

public ECKey.ECDSASignature sign(Sha256Hash input,
                                 @Nullable
                                 org.spongycastle.crypto.params.KeyParameter aesKey)
                          throws KeyCrypterException

Description copied from class: ECKey

Signs the given hash and returns the R and S components as BigIntegers. In the Bitcoin protocol, they are usually encoded using DER format, so you want ECKey.ECDSASignature.encodeToDER() instead. However sometimes the independent components can be useful, for instance, if you're doing to do further EC maths on them.

Overrides:

sign in class ECKey

aesKey - The AES key to use for decryption of the private key. If null then no decryption is required.

Throws:

KeyCrypterException - if there's something wrong with aesKey.

decrypt

public DeterministicKey decrypt(KeyCrypter keyCrypter,
                                org.spongycastle.crypto.params.KeyParameter aesKey)
                         throws KeyCrypterException

Description copied from class: ECKey

Create a decrypted private key with the keyCrypter and AES key supplied. Note that if the aesKey is wrong, this has some chance of throwing KeyCrypterException due to the corrupted padding that will result, but it can also just yield a garbage key.

Overrides:

decrypt in class ECKey

Parameters:

keyCrypter - The keyCrypter that specifies exactly how the decrypted bytes are created.

aesKey - The KeyParameter with the AES encryption key (usually constructed with keyCrypter#deriveKey and cached).

Throws:

KeyCrypterException

decrypt

public DeterministicKey decrypt(org.spongycastle.crypto.params.KeyParameter aesKey)
                         throws KeyCrypterException

Description copied from class: ECKey

Create a decrypted private key with AES key. Note that if the AES key is wrong, this has some chance of throwing KeyCrypterException due to the corrupted padding that will result, but it can also just yield a garbage key.

Overrides:

decrypt in class ECKey

Parameters:

aesKey - The KeyParameter with the AES encryption key (usually constructed with keyCrypter#deriveKey and cached).

Throws:

KeyCrypterException

derive

public DeterministicKey derive(int child)

Derives a child at the given index using hardened derivation. Note: index is not the "i" value. If you want the softened derivation, then use instead HDKeyDerivation.deriveChildKey(this, new ChildNumber(child, false)).

getPrivKey

public BigInteger getPrivKey()

Returns the private key of this deterministic key. Even if this object isn't storing the private key, it can be re-derived by walking up to the parents if necessary and this is what will happen.

Overrides:

getPrivKey in class ECKey

Throws:

IllegalStateException - if the parents are encrypted or a watching chain.

serializePublic

public byte[] serializePublic(NetworkParameters params)

serializePrivate

public byte[] serializePrivate(NetworkParameters params)

serializePubB58

public String serializePubB58(NetworkParameters params)

serializePrivB58

public String serializePrivB58(NetworkParameters params)

deserializeB58

public static DeterministicKey deserializeB58(String base58,
                                              NetworkParameters params)

Deserialize a base-58-encoded HD Key with no parent

deserializeB58

public static DeterministicKey deserializeB58(@Nullable
                                              DeterministicKey parent,
                                              String base58,
                                              NetworkParameters params)

Deserialize a base-58-encoded HD Key.

Parameters:

parent - The parent node in the given key's deterministic hierarchy.

Throws:

IllegalArgumentException - if the base58 encoded key could not be parsed.

deserialize

public static DeterministicKey deserialize(NetworkParameters params,
                                           byte[] serializedKey)

Deserialize an HD Key with no parent

deserialize

public static DeterministicKey deserialize(NetworkParameters params,
                                           byte[] serializedKey,
                                           @Nullable
                                           DeterministicKey parent)

Deserialize an HD Key.

Parameters:

parent - The parent node in the given key's deterministic hierarchy.

getCreationTimeSeconds

public long getCreationTimeSeconds()

The creation time of a deterministic key is equal to that of its parent, unless this key is the root of a tree in which case the time is stored alongside the key as per normal, see ECKey.getCreationTimeSeconds().

Specified by:

getCreationTimeSeconds in interface EncryptableItem

Overrides:

getCreationTimeSeconds in class ECKey

setCreationTimeSeconds

public void setCreationTimeSeconds(long newCreationTimeSeconds)

The creation time of a deterministic key is equal to that of its parent, unless this key is the root of a tree. Thus, setting the creation time on a leaf is forbidden.

Overrides:

setCreationTimeSeconds in class ECKey

equals

public boolean equals(Object o)

Verifies equality of all fields but NOT the parent pointer (thus the same key derived in two separate heirarchy objects will equal each other.

Overrides:

equals in class ECKey

hashCode

public int hashCode()

Overrides:

hashCode in class ECKey

toString

public String toString()

Overrides:

toString in class ECKey

formatKeyWithAddress

public void formatKeyWithAddress(boolean includePrivateKeys,
                                 StringBuilder builder,
                                 NetworkParameters params)

Overrides:

formatKeyWithAddress in class ECKey