Package org.bitcoinj.crypto

Class DeterministicKey

    • Field Detail

      • CHILDNUM_ORDER

        public static final java.util.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​(java.util.List<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        LazyECPoint publicAsPoint,
                        @Nullable
                        java.math.BigInteger priv,
                        @Nullable
                        DeterministicKey parent)
        Constructs a key from its components. This is not normally something you should use.

      • DeterministicKey

        public DeterministicKey​(java.util.List<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        org.bouncycastle.math.ec.ECPoint publicAsPoint,
                        boolean compressed,
                        @Nullable
                        java.math.BigInteger priv,
                        @Nullable
                        DeterministicKey parent)

      • DeterministicKey

        public DeterministicKey​(HDPath hdPath,
                        byte[] chainCode,
                        java.math.BigInteger priv,
                        @Nullable
                        DeterministicKey parent)
        Constructs a key from its components. This is not normally something you should use.

      • DeterministicKey

        public DeterministicKey​(java.util.List<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        LazyECPoint publicAsPoint,
                        @Nullable
                        DeterministicKey parent,
                        int depth,
                        int parentFingerprint)
        Constructs a key from its components, including its public key data and possibly-redundant information about its parent key. Invoked when deserializing, but otherwise not something that you normally should use.

      • DeterministicKey

        public DeterministicKey​(java.util.List<ChildNumber> childNumberPath,
                        byte[] chainCode,
                        java.math.BigInteger priv,
                        @Nullable
                        DeterministicKey parent,
                        int depth,
                        int parentFingerprint)
        Constructs a key from its components, including its private key data and possibly-redundant information about its parent key. Invoked when deserializing, but otherwise not something that you normally should use.

    • Method Detail

      • getPath

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

      • getPathAsString

        public java.lang.String getPathAsString()
        Returns the path of this key as a human-readable string starting with M or 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().

      • 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:
        java.lang.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,
                                AesKey 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

      • 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()
        Description copied from class: ECKey
        Returns true if this key has unencrypted access to private key bytes. Does the opposite of ECKey.isPubKeyOnly().
        Overrides:
        hasPrivKey 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

      • sign

        public ECKey.ECDSASignature sign​(Sha256Hash input,
                                 @Nullable
                                 AesKey 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,
                                AesKey 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​(AesKey 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 java.math.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:
        java.lang.IllegalStateException - if the parents are encrypted or a watching chain.

      • serializePubB58

        public java.lang.String serializePubB58​(Network network,
                                        ScriptType outputScriptType)
        Deprecated.
        Use a serializePubB58(Network) or a descriptor if you need output type information
        Serialize public key to Base58

        outputScriptType should not be used in generating "xpub" format. (and "ypub", "zpub", etc. should not be used)

        Parameters:
        network - which network to serialize key for
        outputScriptType - output script type
        Returns:
        the key serialized as a Base58 address
        See Also:
        Why does importmulti not support zpub and ypub?

      • serializePrivB58

        public java.lang.String serializePrivB58​(Network network,
                                         ScriptType outputScriptType)
        Deprecated.
        Use a serializePrivB58(Network) or a descriptor if you need output type information
        Serialize private key to Base58

        outputScriptType should not be used in generating "xprv" format. (and "zprv", "vprv", etc. should not be used)

        Parameters:
        network - which network to serialize key for
        outputScriptType - output script type
        Returns:
        the key serialized as a Base58 address
        See Also:
        Why does importmulti not support zpub and ypub?

      • serializePubB58

        public java.lang.String serializePubB58​(Network network)
        Serialize public key to Base58 (either "xpub" or "tpub")
        Parameters:
        network - which network to serialize key for
        Returns:
        the key serialized as a Base58 address

      • serializePrivB58

        public java.lang.String serializePrivB58​(Network network)
        Serialize private key to Base58 (either "xprv" or "tprv")
        Parameters:
        network - which network to serialize key for
        Returns:
        the key serialized as a Base58 address

      • deserializeB58

        public static DeterministicKey deserializeB58​(java.lang.String base58,
                                              Network network)
        Deserialize a base-58-encoded HD Key with no parent

      • deserializeB58

        public static DeterministicKey deserializeB58​(@Nullable
                                              DeterministicKey parent,
                                              java.lang.String base58,
                                              Network network)
        Deserialize a base-58-encoded HD Key.
        Parameters:
        parent - The parent node in the given key's deterministic hierarchy.
        Throws:
        java.lang.IllegalArgumentException - if the base58 encoded key could not be parsed.

      • deserialize

        public static DeterministicKey deserialize​(Network network,
                                           byte[] serializedKey)
        Deserialize an HD Key with no parent

      • deserialize

        public static DeterministicKey deserialize​(Network network,
                                           byte[] serializedKey,
                                           @Nullable
                                           DeterministicKey parent)
        Deserialize an HD Key.
        Parameters:
        parent - The parent node in the given key's deterministic hierarchy.

      • getCreationTime

        public java.util.Optional<java.time.Instant> getCreationTime()
        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.getCreationTime().
        Specified by:
        getCreationTime in interface EncryptableItem
        Overrides:
        getCreationTime in class ECKey

      • setCreationTime

        public void setCreationTime​(java.time.Instant creationTime)
        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:
        setCreationTime in class ECKey
        Parameters:
        creationTime - creation time of this key

      • clearCreationTime

        public void clearCreationTime()
        Clears the creation time of this key. This is mainly used deserialization and cloning. Normally you should not need to use this, as keys should have proper creation times whenever possible.
        Overrides:
        clearCreationTime in class ECKey

      • equals

        public boolean equals​(java.lang.Object o)
        Verifies equality of all fields but NOT the parent pointer (thus the same key derived in two separate hierarchy objects will equal each other.
        Overrides:
        equals in class ECKey

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class ECKey

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class ECKey

      • formatKeyWithAddress

        public void formatKeyWithAddress​(boolean includePrivateKeys,
                                 @Nullable
                                 AesKey aesKey,
                                 java.lang.StringBuilder builder,
                                 Network network,
                                 ScriptType outputScriptType,
                                 @Nullable
                                 java.lang.String comment)
        Overrides:
        formatKeyWithAddress in class ECKey