Package org.bitcoinj.core

Class ECKey

  • All Implemented Interfaces:
    EncryptableItem
    Direct Known Subclasses:
    DeterministicKey
    public class ECKey
extends java.lang.Object
implements EncryptableItem

    Represents an elliptic curve public and (optionally) private key, usable for digital signatures but not encryption. Creating a new ECKey with the empty constructor will generate a new random keypair. Other static methods can be used when you already have the public or private parts. If you create a key with only the public part, you can check signatures but not create them.

    ECKey also provides access to Bitcoin Core compatible text message signing, as accessible via the UI or JSON-RPC. This is slightly different to signing raw bytes - if you want to sign your own data and it won't be exposed as text to people, you don't want to use this. If in doubt, ask on the mailing list.

    The ECDSA algorithm supports key recovery in which a signature plus a couple of discriminator bits can be reversed to find the public key used to calculate it. This can be convenient when you have a message and a signature and want to find out who signed it, rather than requiring the user to provide the expected identity.

    This class supports a variety of serialization forms. The methods that accept/return byte arrays serialize private keys as raw byte arrays and public keys using the SEC standard byte encoding for public keys. Signatures are encoded using ASN.1/DER inside the Bitcoin protocol.

    A key can be compressed or uncompressed. This refers to whether the public key is represented when encoded into bytes as an (x, y) coordinate on the elliptic curve, or whether it's represented as just an X co-ordinate and an extra byte that carries a sign bit. With the latter form the Y coordinate can be calculated dynamically, however, because the binary serialization is different the address of a key changes if its compression status is changed. If you deviate from the defaults it's important to understand this: money sent to a compressed version of the key will have a different address to the same key in uncompressed form. Whether a public key is compressed or not is recorded in the SEC binary serialisation format, and preserved in a flag in this class so round-tripping preserves state. Unless you're working with old software or doing unusual things, you can usually ignore the compressed/uncompressed distinction.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ECKey.ECDSASignature
      Groups the two components that make up a signature, and provides a way to encode to DER form, which is how ECDSA signatures are represented when embedded in other data structures in the Bitcoin protocol.
      static class  ECKey.KeyIsEncryptedException  
      static class  ECKey.MissingPrivateKeyException  

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Comparator<ECKey> AGE_COMPARATOR
      Sorts oldest keys first, newest last.
      protected long creationTimeSeconds  
      static org.bouncycastle.crypto.params.ECDomainParameters CURVE
      The parameters of the secp256k1 curve that Bitcoin uses.
      protected EncryptedData encryptedPrivateKey  
      static boolean FAKE_SIGNATURES
      If this global variable is set to true, sign() creates a dummy signature and verify() always returns true.
      static java.math.BigInteger HALF_CURVE_ORDER
      Equal to CURVE.getN().shiftRight(1), used for canonicalising the S value of a signature.
      protected KeyCrypter keyCrypter  
      protected java.math.BigInteger priv  
      protected LazyECPoint pub  
      static java.util.Comparator<ECKey> PUBKEY_COMPARATOR
      Compares pub key bytes using UnsignedBytes.lexicographicalComparator()

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        ECKey()
      Generates an entirely new keypair.
        ECKey​(byte[] privKeyBytes, byte[] pubKey)
      Deprecated.
        ECKey​(java.math.BigInteger privKey, byte[] pubKey, boolean compressed)
      Deprecated.
      protected ECKey​(java.math.BigInteger priv, LazyECPoint pub)  
      protected ECKey​(java.math.BigInteger priv, org.bouncycastle.math.ec.ECPoint pub, boolean compressed)  
        ECKey​(java.security.SecureRandom secureRandom)
      Generates an entirely new keypair with the given SecureRandom object.
        ECKey​(EncryptedData encryptedPrivateKey, byte[] pubKey, KeyCrypter keyCrypter)
      Deprecated.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static LazyECPoint compressPoint​(LazyECPoint point)
      Deprecated.
      Use LazyECPoint.compress()
      ECKey decompress()
      Returns a copy of this key, but with the public point represented in uncompressed form.
      static LazyECPoint decompressPoint​(LazyECPoint point)
      Deprecated.
      Use LazyECPoint.decompress()
      ECKey decrypt​(KeyCrypter keyCrypter, org.bouncycastle.crypto.params.KeyParameter aesKey)
      Create a decrypted private key with the keyCrypter and AES key supplied.
      ECKey decrypt​(org.bouncycastle.crypto.params.KeyParameter aesKey)
      Create a decrypted private key with AES key.
      protected ECKey.ECDSASignature doSign​(Sha256Hash input, java.math.BigInteger privateKeyForSigning)  
      ECKey encrypt​(KeyCrypter keyCrypter, org.bouncycastle.crypto.params.KeyParameter aesKey)
      Create an encrypted private key with the keyCrypter and the AES key supplied.
      static boolean encryptionIsReversible​(ECKey originalKey, ECKey encryptedKey, KeyCrypter keyCrypter, org.bouncycastle.crypto.params.KeyParameter aesKey)
      Check that it is possible to decrypt the key with the keyCrypter and that the original key is returned.
      boolean equals​(java.lang.Object o)  
      byte findRecoveryId​(Sha256Hash hash, ECKey.ECDSASignature sig)
      Returns the recovery ID, a byte with value between 0 and 3, inclusive, that specifies which of 4 possible curve points was used to sign a message.
      void formatKeyWithAddress​(boolean includePrivateKeys, org.bouncycastle.crypto.params.KeyParameter aesKey, java.lang.StringBuilder builder, NetworkParameters params, Script.ScriptType outputScriptType, java.lang.String comment)  
      static ECKey fromASN1​(byte[] asn1privkey)
      Construct an ECKey from an ASN.1 encoded private key.
      static ECKey fromEncrypted​(EncryptedData encryptedPrivateKey, KeyCrypter crypter, byte[] pubKey)
      Constructs a key that has an encrypted private component.
      static ECKey fromPrivate​(byte[] privKeyBytes)
      Creates an ECKey given the private key only.
      static ECKey fromPrivate​(byte[] privKeyBytes, boolean compressed)
      Creates an ECKey given the private key only.
      static ECKey fromPrivate​(java.math.BigInteger privKey)
      Creates an ECKey given the private key only.
      static ECKey fromPrivate​(java.math.BigInteger privKey, boolean compressed)
      Creates an ECKey given the private key only.
      static ECKey fromPrivateAndPrecalculatedPublic​(byte[] priv, byte[] pub)
      Creates an ECKey that simply trusts the caller to ensure that point is really the result of multiplying the generator point by the private key.
      static ECKey fromPrivateAndPrecalculatedPublic​(java.math.BigInteger priv, org.bouncycastle.math.ec.ECPoint pub, boolean compressed)
      Creates an ECKey that simply trusts the caller to ensure that point is really the result of multiplying the generator point by the private key.
      static ECKey fromPublicOnly​(byte[] pub)
      Creates an ECKey that cannot be used for signing, only verifying signatures, from the given encoded point.
      static ECKey fromPublicOnly​(ECKey key)  
      static ECKey fromPublicOnly​(org.bouncycastle.math.ec.ECPoint pub, boolean compressed)
      Creates an ECKey that cannot be used for signing, only verifying signatures, from the given point.
      long getCreationTimeSeconds()
      Returns the creation time of this key or zero if the key was deserialized from a version that did not store that data.
      EncryptedData getEncryptedData()
      An alias for getEncryptedPrivateKey()
      EncryptedData getEncryptedPrivateKey()
      Returns the the encrypted private key bytes and initialisation vector for this ECKey, or null if the ECKey is not encrypted.
      Protos.Wallet.EncryptionType getEncryptionType()
      Returns an enum constant describing what algorithm was used to encrypt the key or UNENCRYPTED.
      KeyCrypter getKeyCrypter()
      Returns the KeyCrypter that was used to encrypt to encrypt this ECKey.
      java.lang.String getPrivateKeyAsHex()  
      java.lang.String getPrivateKeyAsWiF​(NetworkParameters params)  
      DumpedPrivateKey getPrivateKeyEncoded​(NetworkParameters params)
      Exports the private key in the form used by Bitcoin Core's "dumpprivkey" and "importprivkey" commands.
      java.math.BigInteger getPrivKey()
      Gets the private key in the form of an integer field element.
      byte[] getPrivKeyBytes()
      Returns a 32 byte array containing the private key.
      byte[] getPubKey()
      Gets the raw public key value.
      byte[] getPubKeyHash()
      Gets the hash160 form of the public key (as seen in addresses).
      org.bouncycastle.math.ec.ECPoint getPubKeyPoint()
      Gets the public key in the form of an elliptic curve point object from Bouncy Castle.
      java.lang.String getPublicKeyAsHex()  
      byte[] getSecretBytes()
      A wrapper for 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 isCompressed()
      Returns whether this key is using the compressed form or not.
      boolean isEncrypted()
      Indicates whether the private key is encrypted (true) or not (false).
      static boolean isPubKeyCanonical​(byte[] pubkey)
      Returns true if the given pubkey is canonical, i.e.
      static boolean isPubKeyCompressed​(byte[] encoded)
      Returns true if the given pubkey is in its compressed form.
      boolean isPubKeyOnly()
      Returns true if this key doesn't have unencrypted access to private key bytes.
      boolean isWatching()
      Returns true if this key is watch only, meaning it has a public key but no private key.
      ECKey maybeDecrypt​(org.bouncycastle.crypto.params.KeyParameter aesKey)
      Creates decrypted private key if needed.
      static byte[] publicKeyFromPrivate​(java.math.BigInteger privKey, boolean compressed)
      Returns public key bytes from the given private key.
      static org.bouncycastle.math.ec.ECPoint publicPointFromPrivate​(java.math.BigInteger privKey)
      Returns public key point from the given private key.
      static ECKey recoverFromSignature​(int recId, ECKey.ECDSASignature sig, Sha256Hash message, boolean compressed)
      Given the components of a signature and a selector value, recover and return the public key that generated the signature according to the algorithm in SEC1v2 section 4.1.6.
      void setCreationTimeSeconds​(long newCreationTimeSeconds)
      Sets the creation time of this key.
      ECKey.ECDSASignature sign​(Sha256Hash input)
      Signs the given hash and returns the R and S components as BigIntegers.
      ECKey.ECDSASignature sign​(Sha256Hash input, org.bouncycastle.crypto.params.KeyParameter aesKey)
      Signs the given hash and returns the R and S components as BigIntegers.
      static ECKey signedMessageToKey​(java.lang.String message, java.lang.String signatureBase64)
      Given an arbitrary piece of text and a Bitcoin-format message signature encoded in base64, returns an ECKey containing the public key that was used to sign it.
      java.lang.String signMessage​(java.lang.String message)
      Signs a text message using the standard Bitcoin messaging signing format and returns the signature as a base64 encoded string.
      java.lang.String signMessage​(java.lang.String message, org.bouncycastle.crypto.params.KeyParameter aesKey)
      Signs a text message using the standard Bitcoin messaging signing format and returns the signature as a base64 encoded string.
      byte[] toASN1()
      Output this ECKey as an ASN.1 encoded private key, as understood by OpenSSL or used by Bitcoin Core in its wallet storage format.
      java.lang.String toString()  
      java.lang.String toStringWithPrivate​(org.bouncycastle.crypto.params.KeyParameter aesKey, NetworkParameters params)
      Produce a string rendering of the ECKey INCLUDING the private key.
      boolean verify​(byte[] hash, byte[] signature)
      Verifies the given ASN.1 encoded ECDSA signature against a hash using the public key.
      static boolean verify​(byte[] data, byte[] signature, byte[] pub)
      Verifies the given ASN.1 encoded ECDSA signature against a hash using the public key.
      static boolean verify​(byte[] data, ECKey.ECDSASignature signature, byte[] pub)
      Verifies the given ECDSA signature against the message bytes using the public key bytes.
      boolean verify​(Sha256Hash sigHash, ECKey.ECDSASignature signature)
      Verifies the given R/S pair (signature) against a hash using the public key.
      void verifyMessage​(java.lang.String message, java.lang.String signatureBase64)
      Convenience wrapper around signedMessageToKey(String, String).
      void verifyOrThrow​(byte[] hash, byte[] signature)
      Verifies the given ASN.1 encoded ECDSA signature against a hash using the public key, and throws an exception if the signature doesn't match
      void verifyOrThrow​(Sha256Hash sigHash, ECKey.ECDSASignature signature)
      Verifies the given R/S pair (signature) against a hash using the public key, and throws an exception if the signature doesn't match

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • AGE_COMPARATOR

        public static final java.util.Comparator<ECKey> AGE_COMPARATOR
        Sorts oldest keys first, newest last.

      • PUBKEY_COMPARATOR

        public static final java.util.Comparator<ECKey> PUBKEY_COMPARATOR
        Compares pub key bytes using UnsignedBytes.lexicographicalComparator()

      • CURVE

        public static final org.bouncycastle.crypto.params.ECDomainParameters CURVE
        The parameters of the secp256k1 curve that Bitcoin uses.

      • HALF_CURVE_ORDER

        public static final java.math.BigInteger HALF_CURVE_ORDER
        Equal to CURVE.getN().shiftRight(1), used for canonicalising the S value of a signature. If you aren't sure what this is about, you can ignore it.

      • priv

        @Nullable
protected final java.math.BigInteger priv

      • creationTimeSeconds

        protected long creationTimeSeconds

      • encryptedPrivateKey

        protected EncryptedData encryptedPrivateKey

      • FAKE_SIGNATURES

        public static boolean FAKE_SIGNATURES
        If this global variable is set to true, sign() creates a dummy signature and verify() always returns true. This is intended to help accelerate unit tests that do a lot of signing/verifying, which in the debugger can be painfully slow.

    • Constructor Detail

      • ECKey

        public ECKey()
        Generates an entirely new keypair. Point compression is used so the resulting public key will be 33 bytes (32 for the co-ordinate and 1 byte to represent the y bit).

      • ECKey

        public ECKey​(java.security.SecureRandom secureRandom)
        Generates an entirely new keypair with the given SecureRandom object. Point compression is used so the resulting public key will be 33 bytes (32 for the co-ordinate and 1 byte to represent the y bit).

      • ECKey

        protected ECKey​(@Nullable
                java.math.BigInteger priv,
                org.bouncycastle.math.ec.ECPoint pub,
                boolean compressed)

      • ECKey

        protected ECKey​(@Nullable
                java.math.BigInteger priv,
                LazyECPoint pub)

      • ECKey

        @Deprecated
public ECKey​(@Nullable
             byte[] privKeyBytes,
             @Nullable
             byte[] pubKey)
        Deprecated.
        Creates an ECKey given only the private key bytes. This is the same as using the BigInteger constructor, but is more convenient if you are importing a key from elsewhere. The public key will be automatically derived from the private key.

      • ECKey

        @Deprecated
public ECKey​(EncryptedData encryptedPrivateKey,
             byte[] pubKey,
             KeyCrypter keyCrypter)
        Deprecated.
        Create a new ECKey with an encrypted private key, a public key and a KeyCrypter.
        Parameters:
        encryptedPrivateKey - The private key, encrypted,
        pubKey - The keys public key
        keyCrypter - The KeyCrypter that will be used, with an AES key, to encrypt and decrypt the private key

      • ECKey

        @Deprecated
public ECKey​(@Nullable
             java.math.BigInteger privKey,
             @Nullable
             byte[] pubKey,
             boolean compressed)
        Deprecated.
        Creates an ECKey given either the private key only, the public key only, or both. If only the private key is supplied, the public key will be calculated from it (this is slow). If both are supplied, it's assumed the public key already correctly matches the private key. If only the public key is supplied, this ECKey cannot be used for signing.
        Parameters:
        compressed - If set to true and pubKey is null, the derived public key will be in compressed form.

    • Method Detail

      • fromASN1

        public static ECKey fromASN1​(byte[] asn1privkey)
        Construct an ECKey from an ASN.1 encoded private key. These are produced by OpenSSL and stored by Bitcoin Core in its wallet. Note that this is slow because it requires an EC point multiply.

      • fromPrivate

        public static ECKey fromPrivate​(java.math.BigInteger privKey)
        Creates an ECKey given the private key only. The public key is calculated from it (this is slow). The resulting public key is compressed.

      • fromPrivate

        public static ECKey fromPrivate​(java.math.BigInteger privKey,
                                boolean compressed)
        Creates an ECKey given the private key only. The public key is calculated from it (this is slow).
        Parameters:
        compressed - Determines whether the resulting ECKey will use a compressed encoding for the public key.

      • fromPrivate

        public static ECKey fromPrivate​(byte[] privKeyBytes)
        Creates an ECKey given the private key only. The public key is calculated from it (this is slow). The resulting public key is compressed.

      • fromPrivate

        public static ECKey fromPrivate​(byte[] privKeyBytes,
                                boolean compressed)
        Creates an ECKey given the private key only. The public key is calculated from it (this is slow).
        Parameters:
        compressed - Determines whether the resulting ECKey will use a compressed encoding for the public key.

      • fromPrivateAndPrecalculatedPublic

        public static ECKey fromPrivateAndPrecalculatedPublic​(java.math.BigInteger priv,
                                                      org.bouncycastle.math.ec.ECPoint pub,
                                                      boolean compressed)
        Creates an ECKey that simply trusts the caller to ensure that point is really the result of multiplying the generator point by the private key. This is used to speed things up when you know you have the right values already.
        Parameters:
        compressed - Determines whether the resulting ECKey will use a compressed encoding for the public key.

      • fromPrivateAndPrecalculatedPublic

        public static ECKey fromPrivateAndPrecalculatedPublic​(byte[] priv,
                                                      byte[] pub)
        Creates an ECKey that simply trusts the caller to ensure that point is really the result of multiplying the generator point by the private key. This is used to speed things up when you know you have the right values already. The compression state of the point will be preserved.

      • fromPublicOnly

        public static ECKey fromPublicOnly​(org.bouncycastle.math.ec.ECPoint pub,
                                   boolean compressed)
        Creates an ECKey that cannot be used for signing, only verifying signatures, from the given point.
        Parameters:
        compressed - Determines whether the resulting ECKey will use a compressed encoding for the public key.

      • fromPublicOnly

        public static ECKey fromPublicOnly​(byte[] pub)
        Creates an ECKey that cannot be used for signing, only verifying signatures, from the given encoded point. The compression state of pub will be preserved.

      • fromPublicOnly

        public static ECKey fromPublicOnly​(ECKey key)

      • decompress

        public ECKey decompress()
        Returns a copy of this key, but with the public point represented in uncompressed form. Normally you would never need this: it's for specialised scenarios or when backwards compatibility in encoded form is necessary.

      • fromEncrypted

        public static ECKey fromEncrypted​(EncryptedData encryptedPrivateKey,
                                  KeyCrypter crypter,
                                  byte[] pubKey)
        Constructs a key that has an encrypted private component. The given object wraps encrypted bytes and an initialization vector. Note that the key will not be decrypted during this call: the returned ECKey is unusable for signing unless a decryption key is supplied.

      • isPubKeyOnly

        public boolean isPubKeyOnly()
        Returns true if this key doesn't have unencrypted access to private key bytes. This may be because it was never given any private key bytes to begin with (a watching key), or because the key is encrypted. You can use isEncrypted() to tell the cases apart.

      • hasPrivKey

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

      • isWatching

        public boolean isWatching()
        Returns true if this key is watch only, meaning it has a public key but no private key.

      • toASN1

        public byte[] toASN1()
        Output this ECKey as an ASN.1 encoded private key, as understood by OpenSSL or used by Bitcoin Core in its wallet storage format.
        Throws:
        ECKey.MissingPrivateKeyException - if the private key is missing or encrypted.

      • publicKeyFromPrivate

        public static byte[] publicKeyFromPrivate​(java.math.BigInteger privKey,
                                          boolean compressed)
        Returns public key bytes from the given private key. To convert a byte array into a BigInteger, use new BigInteger(1, bytes);

      • publicPointFromPrivate

        public static org.bouncycastle.math.ec.ECPoint publicPointFromPrivate​(java.math.BigInteger privKey)
        Returns public key point from the given private key. To convert a byte array into a BigInteger, use new BigInteger(1, bytes);

      • getPubKeyHash

        public byte[] getPubKeyHash()
        Gets the hash160 form of the public key (as seen in addresses).

      • getPubKey

        public byte[] getPubKey()
        Gets the raw public key value. This appears in transaction scriptSigs. Note that this is not the same as the pubKeyHash/address.

      • getPubKeyPoint

        public org.bouncycastle.math.ec.ECPoint getPubKeyPoint()
        Gets the public key in the form of an elliptic curve point object from Bouncy Castle.

      • getPrivKey

        public java.math.BigInteger getPrivKey()
        Gets the private key in the form of an integer field element. The public key is derived by performing EC point addition this number of times (i.e. point multiplying).
        Throws:
        java.lang.IllegalStateException - if the private key bytes are not available.

      • isCompressed

        public boolean isCompressed()
        Returns whether this key is using the compressed form or not. Compressed pubkeys are only 33 bytes, not 64.

      • sign

        public ECKey.ECDSASignature sign​(Sha256Hash input)
                          throws KeyCrypterException
        Signs the given hash and returns the R and S components as BigIntegers. In the Bitcoin protocol, they are usually encoded using ASN.1 format, so you want toASN1() instead. However sometimes the independent components can be useful, for instance, if you're going to do further EC maths on them.
        Throws:
        KeyCrypterException - if this ECKey doesn't have a private part.

      • sign

        public ECKey.ECDSASignature sign​(Sha256Hash input,
                                 @Nullable
                                 org.bouncycastle.crypto.params.KeyParameter aesKey)
                          throws KeyCrypterException
        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.
        Parameters:
        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.
        ECKey.MissingPrivateKeyException - if this key cannot sign because it's pubkey only.

      • verify

        public static boolean verify​(byte[] data,
                             ECKey.ECDSASignature signature,
                             byte[] pub)

        Verifies the given ECDSA signature against the message bytes using the public key bytes.

        When using native ECDSA verification, data must be 32 bytes, and no element may be larger than 520 bytes.

        Parameters:
        data - Hash of the data to verify.
        signature - ASN.1 encoded signature.
        pub - The public key bytes to use.

      • verify

        public static boolean verify​(byte[] data,
                             byte[] signature,
                             byte[] pub)
                      throws SignatureDecodeException
        Verifies the given ASN.1 encoded ECDSA signature against a hash using the public key.
        Parameters:
        data - Hash of the data to verify.
        signature - ASN.1 encoded signature.
        pub - The public key bytes to use.
        Throws:
        SignatureDecodeException - if the signature is unparseable in some way.

      • verify

        public boolean verify​(byte[] hash,
                      byte[] signature)
               throws SignatureDecodeException
        Verifies the given ASN.1 encoded ECDSA signature against a hash using the public key.
        Parameters:
        hash - Hash of the data to verify.
        signature - ASN.1 encoded signature.
        Throws:
        SignatureDecodeException - if the signature is unparseable in some way.

      • verify

        public boolean verify​(Sha256Hash sigHash,
                      ECKey.ECDSASignature signature)
        Verifies the given R/S pair (signature) against a hash using the public key.

      • verifyOrThrow

        public void verifyOrThrow​(byte[] hash,
                          byte[] signature)
                   throws SignatureDecodeException,
                          java.security.SignatureException
        Verifies the given ASN.1 encoded ECDSA signature against a hash using the public key, and throws an exception if the signature doesn't match
        Throws:
        SignatureDecodeException - if the signature is unparseable in some way.
        java.security.SignatureException - if the signature does not match.

      • verifyOrThrow

        public void verifyOrThrow​(Sha256Hash sigHash,
                          ECKey.ECDSASignature signature)
                   throws java.security.SignatureException
        Verifies the given R/S pair (signature) against a hash using the public key, and throws an exception if the signature doesn't match
        Throws:
        java.security.SignatureException - if the signature does not match.

      • isPubKeyCanonical

        public static boolean isPubKeyCanonical​(byte[] pubkey)
        Returns true if the given pubkey is canonical, i.e. the correct length taking into account compression.

      • isPubKeyCompressed

        public static boolean isPubKeyCompressed​(byte[] encoded)
        Returns true if the given pubkey is in its compressed form.

      • signMessage

        public java.lang.String signMessage​(java.lang.String message)
                             throws KeyCrypterException
        Signs a text message using the standard Bitcoin messaging signing format and returns the signature as a base64 encoded string.
        Throws:
        java.lang.IllegalStateException - if this ECKey does not have the private part.
        KeyCrypterException - if this ECKey is encrypted and no AESKey is provided or it does not decrypt the ECKey.

      • signMessage

        public java.lang.String signMessage​(java.lang.String message,
                                    @Nullable
                                    org.bouncycastle.crypto.params.KeyParameter aesKey)
                             throws KeyCrypterException
        Signs a text message using the standard Bitcoin messaging signing format and returns the signature as a base64 encoded string.
        Throws:
        java.lang.IllegalStateException - if this ECKey does not have the private part.
        KeyCrypterException - if this ECKey is encrypted and no AESKey is provided or it does not decrypt the ECKey.

      • signedMessageToKey

        public static ECKey signedMessageToKey​(java.lang.String message,
                                       java.lang.String signatureBase64)
                                throws java.security.SignatureException
        Given an arbitrary piece of text and a Bitcoin-format message signature encoded in base64, returns an ECKey containing the public key that was used to sign it. This can then be compared to the expected public key to determine if the signature was correct. These sorts of signatures are compatible with the Bitcoin-Qt/bitcoind format generated by signmessage/verifymessage RPCs and GUI menu options. They are intended for humans to verify their communications with each other, hence the base64 format and the fact that the input is text.
        Parameters:
        message - Some piece of human readable text.
        signatureBase64 - The Bitcoin-format message signature in base64
        Throws:
        java.security.SignatureException - If the public key could not be recovered or if there was a signature format error.

      • verifyMessage

        public void verifyMessage​(java.lang.String message,
                          java.lang.String signatureBase64)
                   throws java.security.SignatureException
        Convenience wrapper around signedMessageToKey(String, String). If the key derived from the signature is not the same as this one, throws a SignatureException.
        Throws:
        java.security.SignatureException

      • findRecoveryId

        public byte findRecoveryId​(Sha256Hash hash,
                           ECKey.ECDSASignature sig)
        Returns the recovery ID, a byte with value between 0 and 3, inclusive, that specifies which of 4 possible curve points was used to sign a message. This value is also referred to as "v".
        Throws:
        java.lang.RuntimeException - if no recovery ID can be found.

      • recoverFromSignature

        @Nullable
public static ECKey recoverFromSignature​(int recId,
                                         ECKey.ECDSASignature sig,
                                         Sha256Hash message,
                                         boolean compressed)

        Given the components of a signature and a selector value, recover and return the public key that generated the signature according to the algorithm in SEC1v2 section 4.1.6.

        The recId is an index from 0 to 3 which indicates which of the 4 possible keys is the correct one. Because the key recovery operation yields multiple potential keys, the correct key must either be stored alongside the signature, or you must be willing to try each recId in turn until you find one that outputs the key you are expecting.

        If this method returns null it means recovery was not possible and recId should be iterated.

        Given the above two points, a correct usage of this method is inside a for loop from 0 to 3, and if the output is null OR a key that is not the one you expect, you try again with the next recId.

        Parameters:
        recId - Which possible key to recover.
        sig - the R and S components of the signature, wrapped.
        message - Hash of the data that was signed.
        compressed - Whether or not the original pubkey was compressed.
        Returns:
        An ECKey containing only the public part, or null if recovery wasn't possible.

      • getPrivKeyBytes

        public byte[] getPrivKeyBytes()
        Returns a 32 byte array containing the private key.
        Throws:
        ECKey.MissingPrivateKeyException - if the private key bytes are missing/encrypted.

      • getPrivateKeyEncoded

        public DumpedPrivateKey getPrivateKeyEncoded​(NetworkParameters params)
        Exports the private key in the form used by Bitcoin Core's "dumpprivkey" and "importprivkey" commands. Use the DumpedPrivateKey.toString() method to get the string.
        Parameters:
        params - The network this key is intended for use on.
        Returns:
        Private key bytes as a DumpedPrivateKey.
        Throws:
        java.lang.IllegalStateException - if the private key is not available.

      • getCreationTimeSeconds

        public long getCreationTimeSeconds()
        Returns the creation time of this key or zero if the key was deserialized from a version that did not store that data.
        Specified by:
        getCreationTimeSeconds in interface EncryptableItem

      • setCreationTimeSeconds

        public void setCreationTimeSeconds​(long newCreationTimeSeconds)
        Sets the creation time of this key. Zero is a convention to mean "unavailable". This method can be useful when you have a raw key you are importing from somewhere else.

      • encrypt

        public ECKey encrypt​(KeyCrypter keyCrypter,
                     org.bouncycastle.crypto.params.KeyParameter aesKey)
              throws KeyCrypterException
        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.
        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

      • decrypt

        public ECKey decrypt​(KeyCrypter keyCrypter,
                     org.bouncycastle.crypto.params.KeyParameter aesKey)
              throws KeyCrypterException
        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.
        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 ECKey decrypt​(org.bouncycastle.crypto.params.KeyParameter aesKey)
              throws KeyCrypterException
        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.
        Parameters:
        aesKey - The KeyParameter with the AES encryption key (usually constructed with keyCrypter#deriveKey and cached).
        Throws:
        KeyCrypterException

      • encryptionIsReversible

        public static boolean encryptionIsReversible​(ECKey originalKey,
                                             ECKey encryptedKey,
                                             KeyCrypter keyCrypter,
                                             org.bouncycastle.crypto.params.KeyParameter aesKey)

        Check that it is possible to decrypt the key with the keyCrypter and that the original key is returned.

        Because it is a critical failure if the private keys cannot be decrypted successfully (resulting of loss of all bitcoins controlled by the private key) you can use this method to check when you *encrypt* a wallet that it can definitely be decrypted successfully.

        See Wallet.encrypt(KeyCrypter keyCrypter, KeyParameter aesKey) for example usage.

        Returns:
        true if the encrypted key can be decrypted back to the original key successfully.

      • isEncrypted

        public boolean isEncrypted()
        Indicates whether the private key is encrypted (true) or not (false). A private key is deemed to be encrypted when there is both a KeyCrypter and the encryptedPrivateKey is non-zero.
        Specified by:
        isEncrypted in interface EncryptableItem

      • getSecretBytes

        @Nullable
public byte[] getSecretBytes()
        A wrapper for 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

      • getEncryptedPrivateKey

        @Nullable
public EncryptedData getEncryptedPrivateKey()
        Returns the the encrypted private key bytes and initialisation vector for this ECKey, or null if the ECKey is not encrypted.

      • getKeyCrypter

        @Nullable
public KeyCrypter getKeyCrypter()
        Returns the KeyCrypter that was used to encrypt to encrypt this ECKey. You need this to decrypt the ECKey.

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

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

      • toStringWithPrivate

        public java.lang.String toStringWithPrivate​(@Nullable
                                            org.bouncycastle.crypto.params.KeyParameter aesKey,
                                            NetworkParameters params)
        Produce a string rendering of the ECKey INCLUDING the private key. Unless you absolutely need the private key it is better for security reasons to just use toString().

      • getPrivateKeyAsHex

        public java.lang.String getPrivateKeyAsHex()

      • getPublicKeyAsHex

        public java.lang.String getPublicKeyAsHex()

      • getPrivateKeyAsWiF

        public java.lang.String getPrivateKeyAsWiF​(NetworkParameters params)

      • formatKeyWithAddress

        public void formatKeyWithAddress​(boolean includePrivateKeys,
                                 @Nullable
                                 org.bouncycastle.crypto.params.KeyParameter aesKey,
                                 java.lang.StringBuilder builder,
                                 NetworkParameters params,
                                 Script.ScriptType outputScriptType,
                                 @Nullable
                                 java.lang.String comment)