secp256k1-native
Low-level bindings for bitcoin's secp256k1 elliptic curve library.
Usage
const crypto = require('crypto')
const secp256k1 = require('secp256k1-native')
const signCtx = secp256k1.secp256k1_context_create(secp256k1.secp256k1_context_SIGN)
const verifyCtx = secp256k1.secp256k1_context_create(secp256k1.secp256k1_context_VERIFY)
let seckey
do {
seckey = crypto.randomBytes(32)
} while (!secp256k1.secp256k1_ec_seckey_verify(signCtx, seckey))
const pubkey = Buffer.alloc(64)
secp256k1.secp256k1_ec_pubkey_create(signCtx, pubkey, seckey)
const msg = Buffer.from('Hello, World!')
const msg32 = crypto.createHash('sha256').update(msg).digest()
const sig = Buffer.alloc(64)
secp256k1.secp256k1_ecdsa_sign(signCtx, sig, msg32, seckey)
const result = secp256k1.secp256k1_ecdsa_verify(verifyCtx, sig, msg32, pubkey) ? 'valid' : 'invalid'
console.log('signature is', result)
// signature is validAPI
Constants
secp256k1_SECKEYBYTES = 32secp256k1_PUBKEYBYTES = 64secp256k1_ec_TWEAKBYTES = 32secp256k1_ecdsa_SIGBYTES = 64secp256k1_ecdsa_recoverable_SIGBYTES = 65secp256k1_ecdsa_COMPACTBYTES = 64secp256k1_ecdsa_MSGYBYTES = 32
Context
A context is needed in order to store blinding fators used to protect against side-channel attacks.
var ctx = secp256k1.secp256k1_context_create(flags)
Create a new context in order to protect from side-channel attacks. Returns ctx as a buffer.
Flags:
secp256k1.secp256k1_context_SIGNsecp256k1.secp256k1_context_VERIFYsecp256k1.secp256k1_context_NONEsecp256k1.secp256k1_context_DECLASSIFY
secp256k1.secp256k1_context_randomize(ctx, [seed32])
Randomize a given context. seed32 may be used to pass 32 bytes of entropy or else it should be passed as null.
Keys
secp256k1.secp256k1_ec_pubkey_parse(ctx, pubkey, input)
Parse a 33 or 65 byte secp256k1 public key into the 64 byte internal representation used by the library. The result shall be written to pubkey, which should be a 64 byte buffer. Any ctx may be used.
const size = secp256k1.secp256k1_ec_pubkey_serialize(ctx, output, pubkey, flags)
Serialise a secp256k1 public key to either its 33 or 65 byte representation, the result shall be written to output and the function returns the number of bytes written.
Flags:
secp256k1.secp256k1_ec_COMPRESSEDsecp256k1.secp256k1_ec_UNCOMPRESSED
secp256k1.secp256k1_ec_sekey_verify(ctx, seckey)
Verify seckey is a valid secp256k1 scalar, ie. less than the curve order. Any ctx may be used.
secp256k1.secp256k1_ec_pubkey_create(signCtx, pubkey, seckey)
Compute the public key for a given secp256k1 private key. seckey must be a valid secp256k1 scalar and pubkey should be a buffer of 64 bytes in length. signCtx must have been created with the secp256k1_context_SIGN flag.
secp256k1.secp256k1_ec_privkey_negate(ctx, seckey)
Negate a secp256k1 private key in place. For scalar, x, compute n - x, where n is secp256k1's order. Any ctx may be used.
secp256k1.secp256k1_ec_pubkey_negate(ctx, pubkey)
Negate a secp2561 public key in place. Any ctx may be used.
Key tweaking
sn_secp256k1_ec_privkey_tweak_add(ctx, seckey, tweak)
Tweak a secp256k1 private key in place, by adding a 32 byte tweak to it. Any ctx may be used
sn_secp256k1_ec_privkey_tweak_mul(ctx, seckey, tweak)
Tweak a secp256k1 private key in place, by multiplying with a 32 byte tweak. Any ctx may be used
sn_secp256k1_ec_privkey_tweak_add(verifyCtx, pubkey, tweak)
Tweak a secp256k1 public key in place, by adding a tweak * G to it, where G is the generator. A VERIFY context must be used. pubkey should be a parsed 64 byte internal representation.
sn_secp256k1_ec_privkey_tweak_mul(verifyCtx, pubkey, tweak)
Tweak a secp256k1 public key in place, by multiplying with a 32 byte tweak. A VERIFY context must be used. pubkey should be a parsed 64 byte internal representation.
Signatures
secp256k1.secp256k1_ecdsa_signature_parse_der(ctx, sig, input)
Parse a DER-encoded ECDSA signature into its internal representation. sig should be a 64 byte buffer.
secp256k1.secp256k1_ecdsa_signature_parse_compact(ctx, sig, input64)
Parse a 64 byte ECDSA signature into its internal representation. sig should be a 64 byte buffer.
secp256k1.secp256k1_ecdsa_signature_serialize_der(ctx, output, sig)
Serialise sig to output as a DER-encoded ECDSA signature.
secp256k1.secp256k1_ecdsa_signature_serialize_compact(ctx, output64, sig)
Serialise sig to output as a compact 64 byte ECDSA signature.
const hasChanged = secp256k1.secp256k1_ecdsa_signature_normalize(ctx, sigout, sigin)
Normalise a compact-encoded ECDSA signature to it's lower-S form. Returns a boolean as to whether the signature was changed.
secp256k1.secp256k1_ecdsa_sign(ctx, sig, msg32, seckey)
Compute an ECDSA signature for seckey against msg32, which should be the 32 byte hash of a given message. A SIGN context should be used.
secp256k1.secp256k1_ecdsa_verify(ctx, sig, msg32, pubkey)
Verify an ECDSA signature against a pubkey and msg32. A VERIFY context should be used.
Recoverable signatures
The public key is recoverable from the signature.
secp256k1.secp256k1_ecdsa_recoverable_signature_parse_compact(ctx, sig, input64, recid)
Given the recovery id, recid, parse a 64 byte ECDSA recoverable signature into its 65 byte internal representation. sig should be a 65 byte buffer.
const recid = secp256k1.secp256k1_ecdsa_recoverable_signature_serialize_compact(ctx, output, sig)
Serialize a recoverable ECDSA signature to output in its 64 byte compact-encoded from and return the recovery ID.
secp256k1.secp256k1_ecdsa_recoverable_signature_convert(ctx, sigout, sigin)
Convert an ECDSA recoverable signature to an ECDSA signature. sigin should be secp256k1_ecdsa_recoverable_SIGBYTES and sigout should be secp256k1_ecdsa_SIGBYTES.
secp256k1.secp256k1_ecdsa_sign_recoverable(ctx, sig, msg32, seckey)
Compute an ECDSA recoverable signature for seckey against msg32, which should be the 32 byte hash of a given message. A SIGN context should be used and sig should be secp256k1_ecdsa_recoverable_SIGBYTES.
secp256k1.secp256k1_ecdsa_recover(ctx, pubkey, sig, msg32)
Recover the secp256k1 public key used to create sig from msg32. A VERIFY context should be used and sig should be secp256k1_ecdsa_recoverable_SIGBYTES.
Elliptic Curve Diffie-Hellman
secp256k1_ecdh(ctx, output, point, scalar, [data])
Compute a shared secret by performing an ECDH between a public key, point, and a secret key, scalar, with optional data. output should be a 32 byte buffer and any context may be used.