ECKey (bitcoinj 0.11.2 API)

java.lang.Object
- com.google.bitcoin.core.ECKey

All Implemented Interfaces:

Serializable
```
public class ECKey
extends Object
implements Serializable
```
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 constructors 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-Qt 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.

See Also:
Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and 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.

Field Summary

Fields
Modifier and Type	Field and Description
`static org.spongycastle.crypto.params.ECDomainParameters`	`CURVE` The parameters of the secp256k1 curve that Bitcoin uses.
`static boolean`	`FAKE_SIGNATURES` If this global variable is set to true, sign() creates a dummy signature and verify() always returns true.
`static BigInteger`	`HALF_CURVE_ORDER` Equal to CURVE.getN().shiftRight(1), used for canonicalising the S value of a signature.

Constructor Summary

Constructors
Constructor and Description
`ECKey()` Generates an entirely new keypair.
`ECKey(BigInteger privKey)` Creates an ECKey given the private key only.
`ECKey(BigInteger privKey, BigInteger pubKey)` A constructor variant with BigInteger pubkey.
`ECKey(BigInteger privKey, byte[] pubKey, boolean compressed)` Creates an ECKey given either the private key only, the public key only, or both.
`ECKey(byte[] privKeyBytes, byte[] pubKey)` Creates an ECKey given only the private key bytes.
`ECKey(EncryptedPrivateKey encryptedPrivateKey, byte[] pubKey, KeyCrypter keyCrypter)` Create a new ECKey with an encrypted private key, a public key and a KeyCrypter.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearPrivateKey()` Clears all the ECKey private key contents from memory.
`ECKey`	`decrypt(KeyCrypter keyCrypter, org.spongycastle.crypto.params.KeyParameter aesKey)` Create a decrypted private key with the keyCrypter and AES key supplied.
`ECKey`	`encrypt(KeyCrypter keyCrypter, org.spongycastle.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.spongycastle.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(Object o)`
`static ECKey`	`fromASN1(byte[] asn1privkey)` Construct an ECKey from an ASN.1 encoded private key.
`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.
`EncryptedPrivateKey`	`getEncryptedPrivateKey()`
`KeyCrypter`	`getKeyCrypter()`
`DumpedPrivateKey`	`getPrivateKeyEncoded(NetworkParameters params)` Exports the private key in the form used by the Satoshi client "dumpprivkey" and "importprivkey" commands.
`byte[]`	`getPrivKeyBytes()` Returns a 32 byte array containing the private key, or null if the key is encrypted or public only
`byte[]`	`getPubKey()` Gets the raw public key value.
`byte[]`	`getPubKeyHash()` Gets the hash160 form of the public key (as seen in addresses).
`int`	`hashCode()`
`boolean`	`hasPrivKey()`
`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).
`boolean`	`isPubKeyCanonical()` Returns true if this pubkey is canonical, i.e.
`static boolean`	`isPubKeyCanonical(byte[] pubkey)` Returns true if the given pubkey is canonical, i.e.
`boolean`	`isPubKeyOnly()`
`static byte[]`	`publicKeyFromPrivate(BigInteger privKey, boolean compressed)` Returns public key bytes 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.spongycastle.crypto.params.KeyParameter aesKey)` Signs the given hash and returns the R and S components as BigIntegers.
`static ECKey`	`signedMessageToKey(String message, 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.
`String`	`signMessage(String message)` Signs a text message using the standard Bitcoin messaging signing format and returns the signature as a base64 encoded string.
`String`	`signMessage(String message, org.spongycastle.crypto.params.KeyParameter aesKey)` Signs a text message using the standard Bitcoin messaging signing format and returns the signature as a base64 encoded string.
`Address`	`toAddress(NetworkParameters params)` Returns the address that corresponds to the public part of this ECKey.
`byte[]`	`toASN1()` Output this ECKey as an ASN.1 encoded private key, as understood by OpenSSL or used by the BitCoin reference implementation in its wallet storage format.
`String`	`toString()`
`String`	`toStringWithPrivate()` Produce a string rendering of the ECKey INCLUDING the private key.
`boolean`	`verify(byte[] data, 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(String message, String signatureBase64)` Convenience wrapper around `signedMessageToKey(String, String)`.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - CURVE
```
public static final org.spongycastle.crypto.params.ECDomainParameters CURVE
```
    The parameters of the secp256k1 curve that Bitcoin uses.
  - HALF_CURVE_ORDER
```
public static final 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.
  - 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(BigInteger privKey)
```
    Creates an ECKey given the private key only. The public key is calculated from it (this is slow)
  - ECKey
```
public ECKey(BigInteger privKey,
     BigInteger pubKey)
```
    A constructor variant with BigInteger pubkey. See ECKey(BigInteger, byte[]).
  - ECKey
```
public ECKey(@Nullable
     byte[] privKeyBytes,
     @Nullable
     byte[] pubKey)
```
    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
```
public ECKey(@Nullable
     EncryptedPrivateKey encryptedPrivateKey,
     @Nullable
     byte[] pubKey,
     KeyCrypter keyCrypter)
```
    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
```
public ECKey(@Nullable
     BigInteger privKey,
     @Nullable
     byte[] pubKey,
     boolean compressed)
```
    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 public 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 the Bitcoin reference implementation in its wallet. Note that this is slow because it requires an EC point multiply.
  - isPubKeyOnly
```
public boolean isPubKeyOnly()
```
  - hasPrivKey
```
public boolean hasPrivKey()
```
  - toASN1
```
public byte[] toASN1()
```
    Output this ECKey as an ASN.1 encoded private key, as understood by OpenSSL or used by the BitCoin reference implementation in its wallet storage format.
  - publicKeyFromPrivate
```
public static byte[] publicKeyFromPrivate(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);
  - 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.
  - isCompressed
```
public boolean isCompressed()
```
    Returns whether this key is using the compressed form or not. Compressed pubkeys are only 33 bytes, not 64.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toStringWithPrivate
```
public String toStringWithPrivate()
```
    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().
  - toAddress
```
public Address toAddress(NetworkParameters params)
```
    Returns the address that corresponds to the public part of this ECKey. Note that an address is derived from the RIPEMD-160 hash of the public key and is not the public key itself (which is too large to be convenient).
  - clearPrivateKey
```
public void clearPrivateKey()
```
    Clears all the ECKey private key contents from memory. WARNING - this method irreversibly deletes the private key information. It turns the ECKEy into a watch only key.
  - 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 DER format, so you want toASN1() instead. However sometimes the independent components can be useful, for instance, if you're doing 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.spongycastle.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 this ECKey doesn't have a private part.
  - 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)
```
    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.
  - verify
```
public boolean verify(byte[] data,
             byte[] signature)
```
    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.
  - verify
```
public boolean verify(Sha256Hash sigHash,
             ECKey.ECDSASignature signature)
```
    Verifies the given R/S pair (signature) against a hash using the public key.
  - isPubKeyCanonical
```
public boolean isPubKeyCanonical()
```
    Returns true if this pubkey is canonical, i.e. the correct length taking into account compression.
  - isPubKeyCanonical
```
public static boolean isPubKeyCanonical(byte[] pubkey)
```
    Returns true if the given pubkey is canonical, i.e. the correct length taking into account compression.
  - signMessage
```
public String signMessage(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:
    
    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 String signMessage(String message,
                 @Nullable
                 org.spongycastle.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:
    
    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(String message,
                       String signatureBase64)
                                throws 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:
    
    SignatureException - If the public key could not be recovered or if there was a signature format error.
  - verifyMessage
```
public void verifyMessage(String message,
                 String signatureBase64)
                   throws 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:
    
    SignatureException
  - 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
```
@Nullable
public byte[] getPrivKeyBytes()
```
    Returns a 32 byte array containing the private key, or null if the key is encrypted or public only
  - getPrivateKeyEncoded
```
public DumpedPrivateKey getPrivateKeyEncoded(NetworkParameters params)
```
    Exports the private key in the form used by the Satoshi client "dumpprivkey" and "importprivkey" commands. Use the VersionedChecksummedBytes.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:
    
    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.
  - 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.
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - encrypt
```
public ECKey encrypt(KeyCrypter keyCrypter,
            org.spongycastle.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. To be secure you need to clear the original, unencrypted private key bytes.
    
    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.spongycastle.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).
    
    Returns:
    unencryptedKey
    
    Throws:
    
    KeyCrypterException
  - encryptionIsReversible
```
public static boolean encryptionIsReversible(ECKey originalKey,
                             ECKey encryptedKey,
                             KeyCrypter keyCrypter,
                             org.spongycastle.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.
  - getEncryptedPrivateKey
```
@Nullable
public EncryptedPrivateKey getEncryptedPrivateKey()
```
    Returns:
    The encryptedPrivateKey (containing the encrypted private key bytes and initialisation vector) for this ECKey, or null if the ECKey is not encrypted.
  - getKeyCrypter
```
public KeyCrypter getKeyCrypter()
```
    Returns:
    The KeyCrypter that was used to encrypt to encrypt this ECKey. You need this to decrypt the ECKey.

Class ECKey

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CURVE

HALF_CURVE_ORDER

FAKE_SIGNATURES

Constructor Detail

ECKey

ECKey

ECKey

ECKey

ECKey

ECKey

Method Detail

fromASN1

isPubKeyOnly

hasPrivKey

toASN1

publicKeyFromPrivate

getPubKeyHash

getPubKey

isCompressed

toString

toStringWithPrivate

toAddress

clearPrivateKey

sign

sign

verify

verify

verify

verify

isPubKeyCanonical

isPubKeyCanonical

signMessage

signMessage

signedMessageToKey

verifyMessage

recoverFromSignature

getPrivKeyBytes

getPrivateKeyEncoded

getCreationTimeSeconds

setCreationTimeSeconds

equals

hashCode

encrypt

decrypt

encryptionIsReversible

isEncrypted

getEncryptedPrivateKey

getKeyCrypter