Class Secp256k1Foreign

java.lang.Object
org.bitcoinj.secp.ffm.Secp256k1Foreign
All Implemented Interfaces:
Closeable, AutoCloseable, Secp256k1
public class Secp256k1Foreign extends Object implements AutoCloseable, Secp256k1

Implementation of Secp256k1 using the secp256k1 C-language library and the Java Foreign Function & Memory API.

Memory management

Every API method that needs off-heap (native) memory creates a temporary, thread-scoped "confined" Arena (via Arena.ofConfined()) for the duration of that call, so all native allocations are deterministically released (via Arena.close()]) when the call returns.

We use ta as the name for these temporary/thread arenas.

Helper methods never create an arena of their own -- they take a SegmentAllocator so that the caller retains control over the lifetime of everything that is allocated on its behalf. Any MemorySegment returned by a helper is therefore only valid until the caller's arena is closed.

The only native resource with a lifetime longer than a single call is the secp256k1_context, which is allocated and freed by the C library itself (see close()).

  • Constructor Details

    • Secp256k1Foreign

      public Secp256k1Foreign()

    • Secp256k1Foreign

      public Secp256k1Foreign(int flags, boolean randomize)

  • Method Details

    • ecdsaVerify

      public static boolean ecdsaVerify(MemorySegment sig, MemorySegment msg_hash, MemorySegment pubkey)
      TBD: Static verify method that doesn't require a class instance.

    • close

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

    • ecPrivKeyCreate

      public SecpPrivKey ecPrivKeyCreate()
      Description copied from interface: Secp256k1
      Create a new, randomly-generated private key.
      Specified by:
      ecPrivKeyCreate in interface Secp256k1
      Returns:
      the private key

    • ecPubKeyCreate

      public SecpPubKey ecPubKeyCreate(SecpPrivKey privkey)
      Description copied from interface: Secp256k1
      Create a public key from the given private key.
      Specified by:
      ecPubKeyCreate in interface Secp256k1
      Parameters:
      privkey - the private key
      Returns:
      derived public key

    • ecKeyPairCreate

      public SecpKeyPair ecKeyPairCreate()
      Description copied from interface: Secp256k1
      Create a new, randomly-generated private key and return it with its matching public key
      Specified by:
      ecKeyPairCreate in interface Secp256k1
      Returns:
      newly generated key pair

    • ecKeyPairCreate

      public SecpKeyPair ecKeyPairCreate(SecpPrivKey privKey)
      Description copied from interface: Secp256k1
      Create a key pair structure from a known private key
      Specified by:
      ecKeyPairCreate in interface Secp256k1
      Parameters:
      privKey - the private key
      Returns:
      object containing both public and private key

    • ecPubKeyTweakMul

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

    • ecPubKeyCombine

      public SecpPubKey ecPubKeyCombine(SecpPoint.Uncompressed key1, SecpPoint.Uncompressed key2)
      Description copied from interface: Secp256k1
      Combine two public keys by adding them.
      Specified by:
      ecPubKeyCombine in interface Secp256k1
      Parameters:
      key1 - first key
      key2 - second key
      Returns:
      the sum

    • ecPubKeyCombine

      public SecpPubKey ecPubKeyCombine(SecpPubKey key1)

    • ecPubKeySerialize

      public byte[] ecPubKeySerialize(SecpPubKey pubKey, int flags)
      Since PubKeyData is serializable without using the native lib, this method serialized without a native call.
      Specified by:
      ecPubKeySerialize in interface Secp256k1
      Parameters:
      pubKey -
      flags -
      Returns:

    • ecPubKeyParse

      public SecpResult<SecpPubKey> ecPubKeyParse(byte[] inputData)
      Description copied from interface: Secp256k1
      Parse a byte array as a public key
      Specified by:
      ecPubKeyParse in interface Secp256k1
      Parameters:
      inputData - raw data to parse as public key
      Returns:
      public key result or error

    • xOnlyPubKeyParse

      public SecpResult<SecpXOnlyPubKey> xOnlyPubKeyParse(byte[] inputData)
      Description copied from interface: Secp256k1
      Parse a byte array as an x-only public key
      Specified by:
      xOnlyPubKeyParse in interface Secp256k1
      Parameters:
      inputData - raw data to parse as an x-only public key
      Returns:
      an x-only public key result or error

    • ecdsaSign

      public SecpResult<EcdsaSignature> ecdsaSign(byte[] msg_hash_data, SecpPrivKey privKey)
      Description copied from interface: Secp256k1
      Sign a message hash using the ECDSA algorithm
      Specified by:
      ecdsaSign in interface Secp256k1
      Parameters:
      msg_hash_data - 32-byte hash of message to sign
      privKey - private key
      Returns:
      the signature

    • ecdsaSignLowR

      public SecpResult<EcdsaSignature> ecdsaSignLowR(byte[] msg_hash_data, SecpPrivKey privKey)
      ECDSA signing with Low-R grinding. Will potentially sign multiple times until a low-R signature is generated.
      Specified by:
      ecdsaSignLowR in interface Secp256k1
      Parameters:
      msg_hash_data - hashed message data
      privKey - private key
      Returns:
      A result, which on success contains a valid signature with a low R value.

    • ecdsaSignatureSerializeCompact

      public byte[] ecdsaSignatureSerializeCompact(EcdsaSignature sig)
      Description copied from interface: Secp256k1
      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.
      Specified by:
      ecdsaSignatureSerializeCompact in interface Secp256k1
      Parameters:
      sig - signature object
      Returns:
      compact signature bytes

    • ecdsaSignatureParseCompact

      public SecpResult<EcdsaSignature> ecdsaSignatureParseCompact(byte[] serialized_signature)
      Description copied from interface: Secp256k1
      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.
      Specified by:
      ecdsaSignatureParseCompact in interface Secp256k1
      Parameters:
      serialized_signature - compact signature bytes
      Returns:
      signature object

    • ecdsaVerify

      public SecpResult<Boolean> ecdsaVerify(EcdsaSignature sig, byte[] msg_hash_data, SecpPubKey pubKey)
      Description copied from interface: Secp256k1
      Verify an ECDSA signature.
      Specified by:
      ecdsaVerify in interface Secp256k1
      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

      public byte[] taggedSha256(byte[] tag, byte[] message)
      Description copied from interface: Secp256k1
      Generate a tagged SHA-256 hash.
      Specified by:
      taggedSha256 in interface Secp256k1
      Parameters:
      tag - a tag specifying the context of usage
      message - the message itself
      Returns:
      the SHA-256 HASH

    • schnorrSigSign32

      public SchnorrSignature schnorrSigSign32(byte[] messageHash, SecpPrivKey privKey)
      Description copied from interface: Secp256k1
      Create a Schnorr signature for a message.
      Specified by:
      schnorrSigSign32 in interface Secp256k1
      Parameters:
      messageHash - a hash of a message to sign
      privKey - private key for signing
      Returns:
      the signature

    • schnorrSigSign32

      public SchnorrSignature schnorrSigSign32(byte[] messageHash, SecpPrivKey privKey, byte[] auxiliaryRandom)
      schnorrSigSign32 using provided randomness. This is not part of the API and is intended for testing.
      Specified by:
      schnorrSigSign32 in interface Secp256k1
      Parameters:
      messageHash - message hash
      privKey - private key
      auxiliaryRandom - auxiliary randomness (typically from a test vector)
      Returns:
      the signature

    • schnorrSigVerify

      public SecpResult<Boolean> schnorrSigVerify(SchnorrSignature signature, byte[] msg_hash, SecpXOnlyPubKey pubKey)
      Description copied from interface: Secp256k1
      Verify a Schnorr signature.
      Specified by:
      schnorrSigVerify in interface Secp256k1
      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

    • ecdh

      public SecpResult<EcdhSharedSecret> ecdh(SecpPubKey pubKey, SecpPrivKey privKey)
      Description copied from interface: Secp256k1
      ECDH key agreement
      Specified by:
      ecdh in interface Secp256k1
      Parameters:
      pubKey - pubkey of the other party
      privKey - private key
      Returns:
      ecdh key agreement

    • toString

      public String toString()
      Overrides:
      toString in class Object