Interface Secp256k1

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
Secp256k1Foreign
public interface Secp256k1 extends Closeable
Main interface providing Elliptic Curve Cryptography functions using the SECG curve. secp256k1.

The API is based on the C-language API of libsecp256k1, but is here adapted to modern, idiomatic, functional-style Java and use Elliptic Curve types from the Java Class Library, such as ECPublicKey via the specialized SecpPubKey subclass.

Two implementations are being developed.

  • Field Details

    • P

      static final BigInteger P
      The prime P, that defines the secp256k1 field.

      P = 2²⁵⁶ − 2³² − 2⁹ − 2⁸ − 2⁷ − 2⁶ − 2⁴ − 1

      Note that since the maximum valid value of a field element is P - 1, this constant cannot be represented as a SecpFieldElement, so we use BigInteger instead.

    • N

      static final BigInteger N
      The prime N, that represents the order of the generator point, i.e. the number of points on the curve.

    • G

      static final SecpPoint.Uncompressed G
      The generator point G (also known as base point) for secp256k1.

    • FIELD

      static final ECFieldFp FIELD
      The secp256k1 field definition p using the standard Java type

    • CURVE

      static final EllipticCurve CURVE
      The curve definition for secp256k1 using the standard Java type EllipticCurve.

      The curve equation is y² = x³ + ax + b, where: a = 0, b = 7, resulting in:

      y² = x³ + 7

      over the field FIELD, which is 0..P

    • EC_PARAMS

      static final ECParameterSpec EC_PARAMS
      The secp256k1 domain parameters definition using the standard Java type

    • HALF_CURVE_ORDER

      static final SecpFieldElement HALF_CURVE_ORDER
      Equal to EC_PARAMS.getOrder().shiftRight(1), used for canonicalizing the S value of a signature. If you aren't sure what this is about, you can ignore it.

  • Method Details

    • all

      static Stream<Secp256k1.Provider> all()
      Get a stream of all known providers
      Returns:
      stream of all known providers

    • findAll

      static Stream<Secp256k1.Provider> findAll(Predicate<Secp256k1.Provider> filter)
      Get a stream of all providers that match a filter
      Parameters:
      filter - filter function to select providers
      Returns:
      stream of matching providers

    • ecPrivKeyCreate

      SecpPrivKey ecPrivKeyCreate()
      Create a new, randomly-generated private key.
      Returns:
      the private key

    • ecPubKeyCreate

      SecpPubKey ecPubKeyCreate(SecpPrivKey privKey)
      Create a public key from the given private key.
      Parameters:
      privKey - the private key
      Returns:
      derived public key

    • ecKeyPairCreate

      SecpKeyPair ecKeyPairCreate()
      Create a new, randomly-generated private key and return it with its matching public key
      Returns:
      newly generated key pair

    • ecKeyPairCreate

      SecpKeyPair ecKeyPairCreate(SecpPrivKey privKey)
      Create a key pair structure from a known private key
      Parameters:
      privKey - the private key
      Returns:
      object containing both public and private key

    • ecPubKeyTweakMul

      SecpPubKey ecPubKeyTweakMul(SecpPoint.Uncompressed pubKey, BigInteger scalarMultiplier)
      Multiply a public key by a scalar, this is known as key "tweaking"
      Parameters:
      pubKey - public key representing a point on the curve
      scalarMultiplier - scalar multiplier
      Returns:
      the product

    • ecPubKeyCombine

      SecpPubKey ecPubKeyCombine(SecpPoint.Uncompressed key1, SecpPoint.Uncompressed key2)
      Combine two public keys by adding them.
      Parameters:
      key1 - first key
      key2 - second key
      Returns:
      the sum

    • ecPubKeySerialize

      byte[] ecPubKeySerialize(SecpPubKey pubKey, int flags)
      Serialize a public key
      Parameters:
      pubKey - public key to serialize
      flags - serialization flags
      Returns:
      pubKey serialized as a byte array

    • ecPointUncompress

      default SecpPoint.Uncompressed ecPointUncompress(SecpPoint.Compressed compressedPoint)
      Calculate an uncompressed point from a compressed point.
      Parameters:
      compressedPoint - a compressed point
      Returns:
      The same point, in uncompressed format

    • ecPubKeyParse

      SecpResult<SecpPubKey> ecPubKeyParse(byte[] inputData)
      Parse a byte array as a public key
      Parameters:
      inputData - raw data to parse as public key
      Returns:
      public key result or error

    • ecPubKeyFromXOnly

      default SecpPubKey ecPubKeyFromXOnly(SecpXOnlyPubKey xOnlyPubKey)
      Convert an x-only public key to a (uncompressed point) public key
      Parameters:
      xOnlyPubKey - x-only public key
      Returns:
      public key

    • xOnlyPubKeyParse

      SecpResult<SecpXOnlyPubKey> xOnlyPubKeyParse(byte[] inputData)
      Parse a byte array as an x-only public key
      Parameters:
      inputData - raw data to parse as an x-only public key
      Returns:
      an x-only public key result or error

    • ecdsaSign

      SecpResult<EcdsaSignature> ecdsaSign(byte[] msg_hash_data, SecpPrivKey privKey)
      Sign a message hash using the ECDSA algorithm
      Parameters:
      msg_hash_data - 32-byte hash of message to sign
      privKey - private key
      Returns:
      the signature

    • ecdsaSignLowR

      SecpResult<EcdsaSignature> ecdsaSignLowR(byte[] messageHashData, SecpPrivKey privKey)
      Sign a message hash using the ECDSA algorithm and Low-R signature griding

      This uses the same nonce-incrementing algorithm as Bitcoin Core to ensure a low-R signature.

      Parameters:
      messageHashData - 32-byte hash of message to sign
      privKey - private key
      Returns:
      the signature

    • ecdsaSignatureSerializeCompact

      byte[] ecdsaSignatureSerializeCompact(EcdsaSignature sig)
      Serialize a EcdsaSignature as a Bitcoin compact signature. A compact signature is the two signature component field integers (known as r and s) serialized in-order as binary data in big-endian format.
      Parameters:
      sig - signature object
      Returns:
      compact signature bytes

    • ecdsaSignatureParseCompact

      SecpResult<EcdsaSignature> ecdsaSignatureParseCompact(byte[] serialized_signature)
      Parse a Bitcoin compact signature. A compact signature is the two signature component field integers (known as r and s) serialized in-order as binary data in big-endian format.
      Parameters:
      serialized_signature - compact signature bytes
      Returns:
      signature object

    • ecdsaVerify

      SecpResult<Boolean> ecdsaVerify(EcdsaSignature sig, byte[] msg_hash_data, SecpPubKey pubKey)
      Verify an ECDSA signature.
      Parameters:
      sig - The signature to verify.
      msg_hash_data - A 32-byte hash of the message to verify.
      pubKey - The pubkey that must have signed the message
      Returns:
      true, false, or error

    • taggedSha256

      default byte[] taggedSha256(String tag, String message)
      Generate a tagged SHA-256 hash.
      Parameters:
      tag - a tag specifying the context of usage
      message - the message itself
      Returns:
      the SHA-256 HASH

    • taggedSha256

      byte[] taggedSha256(byte[] tag, byte[] message)
      Generate a tagged SHA-256 hash.
      Parameters:
      tag - a tag specifying the context of usage
      message - the message itself
      Returns:
      the SHA-256 HASH

    • schnorrSigSign32

      SchnorrSignature schnorrSigSign32(byte[] msg_hash, SecpPrivKey privKey)
      Create a Schnorr signature for a message.
      Parameters:
      msg_hash - a hash of a message to sign
      privKey - private key for signing
      Returns:
      the signature

    • schnorrSigSign32

      SchnorrSignature schnorrSigSign32(byte[] messageHash, SecpPrivKey privKey, byte[] auxiliaryRandom)
      Create a Schnorr signature for a message.
      Parameters:
      messageHash - a hash of a message to sign
      privKey - private key for signing
      auxiliaryRandom - auxiliary randomness (typically from a test vector)
      Returns:
      the signature

    • schnorrSigVerify

      SecpResult<Boolean> schnorrSigVerify(SchnorrSignature signature, byte[] msg_hash, SecpXOnlyPubKey pubKey)
      Verify a Schnorr signature.
      Parameters:
      signature - the signature to verify
      msg_hash - hash of the message
      pubKey - x-only pubkey that must have signed the message
      Returns:
      true, false, or error

    • schnorrSigVerify

      default SecpResult<Boolean> schnorrSigVerify(SchnorrSignature signature, byte[] msg_hash, SecpPubKey pubKey)
      Verify a Schnorr signature.
      Parameters:
      signature - the signature to verify
      msg_hash - hash of the message
      pubKey - pubkey that must have signed the message
      Returns:
      true, false, or error

    • ecdh

      SecpResult<EcdhSharedSecret> ecdh(SecpPubKey pubKey, SecpPrivKey privKey)
      ECDH key agreement
      Parameters:
      pubKey - pubkey of the other party
      privKey - private key
      Returns:
      ecdh key agreement

    • close

      void close()
      Override close and declare that no checked exceptions are thrown
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • get

      static Secp256k1 get()
      Get the default implementation
      Returns:
      A Secp256k1 instance using the default implementation

    • getById

      static Secp256k1 getById(String id)
      Get implementation by ID
      Parameters:
      id - implementation ID
      Returns:
      A Secp256k1 instance using the default implementation

    • getById

      static Secp256k1 getById(Secp256k1.ProviderId idEnum)
      Get implementation by ID enum
      Parameters:
      idEnum - implementation ID enum
      Returns:
      A Secp256k1 instance using the default implementation