libsecp256k1: secp256k1 Keys and ECDSA Signatures
| (require libsecp256k1) | package: libsecp256k1 |
FFI bindings to Bitcoin Core’s libsecp256k1 C library: secret and public keys on the secp256k1 curve, deterministic ECDSA signatures, public key recovery and key tweaks. This is not the pure-Racket secp256k1 package.
This manual has two parts: the Guide works through the library by task, and the Reference documents every binding.
Security. A secret key prints as #<secret-key>. No error from this library shows an argument: a contract violation, a wrong argument count or an unknown keyword names what was expected and the kind and length of what was given, never the value. The named contracts keep that guarantee only inside this library; secret-bytes/c in a caller’s own -> contract prints the value like any other contract. Racket’s memory manager may copy key bytes, so this library cannot erase them from memory.
Installation. The package ships a prebuilt libsecp256k1 0.8.0 for x86_64 Linux (glibc 2.17 or later) and Apple-silicon macOS only, and installing copies it into place; nothing is compiled. On every other platform, including ARM Linux, Intel macOS and Windows, install the operating system’s libsecp256k1 0.2 or later, built with the recovery module, or name a library file with LIBSECP256K1_LIBRARY; see libsecp256k1-origin.
License. This package is distributed under Apache-2.0 OR MIT; the bundled libsecp256k1 library is distributed under MIT, with its notice in "native-libs/LICENSE.libsecp256k1".
Acknowledgements. The libsecp256k1 contributors.
AI Disclosure. This package and its documentation were created with the use of AI tools.
1 Guide
This guide works through the library by task, one section per task. Each section ends with an example program in the package’s "examples" directory that does the same task end to end; run one with
racket -l libsecp256k1/examples/01-sign-verify
For the full definition of every binding, see the Reference.
1.1 Keys
A secret key is an integer in [1, n), where n is secp256k1-order, stored as 32 big-endian bytes. generate-secret-key draws one from the operating system’s random source; bytes->secret-key and integer->secret-key rebuild a stored one. A secret key prints as #<secret-key>, and secret keys are equal? only when they are the same object, so compare their public keys.
The public key, secret-key->public-key, is safe to share. Its compressed form is 33 bytes and its uncompressed form 65; bytes->public-key reads either. An integer, or bytes of the right length, that is not a valid key raises exn:fail:libsecp256k1:key; bytes of another length are a contract violation. No error from this library shows the value it was given.
> (define key (generate-secret-key)) > key #<secret-key>
> (define public (secret-key->public-key key)) > (define stored (secret-key->bytes key)) > (equal? (bytes->secret-key stored) key) #f
> (equal? (secret-key->public-key (bytes->secret-key stored)) public) #t
> (bytes-length (public-key->bytes public)) 33
> (bytes-length (public-key->bytes public #:compressed? #f)) 65
> (equal? (bytes->public-key (public-key->bytes public #:compressed? #f)) public) #t
> (bytes->secret-key (make-bytes 32 0))
bytes->secret-key: invalid secret key;
the value is zero or not less than the curve order
See "examples/00-keys.rkt".
1.2 Signing and Verifying
ECDSA signs a 32-byte digest, not a message: hash the message first, here with sha256-bytes. ecdsa-sign takes its nonce from RFC 6979, so the same key and digest always give the same signature, and it returns only low-S signatures. ecdsa-verify rejects high-S signatures; pass a signature from elsewhere through ecdsa-signature-normalize first.
> (define digest (sha256-bytes #"hello")) > (define sig (ecdsa-sign digest key)) > (ecdsa-verify sig digest public) #t
> (ecdsa-verify sig (sha256-bytes #"hello!") public) #f
> (equal? (ecdsa-sign digest key) sig) #t
> (ecdsa-signature-low-s? sig) #t
See "examples/01-sign-verify.rkt".
1.3 Public Key Recovery
A recoverable signature carries, beside r and s, a recovery id from 0 to 3 that picks the signer’s public key among those the signature and digest allow. ecdsa-recover computes that key, so a signed message need not carry its signer; this is how Ethereum identifies the sender of a transaction. Another digest usually recovers another key rather than failing, so compare the result with the signer you expect. A recoverable signature is also a plain one for ecdsa-verify.
> (define rsig (ecdsa-sign-recoverable digest key)) > (equal? (ecdsa-recover rsig digest) public) #t
> (public-key? (ecdsa-recover rsig (sha256-bytes #"hello!"))) #t
> (equal? (ecdsa-recover rsig (sha256-bytes #"hello!")) public) #f
> (ecdsa-verify rsig digest public) #t
"examples/02-recover.rkt" packs a signature as Ethereum’s 65 bytes r ‖ s ‖ v, with v = 27 + id for an id of 0 or 1, and recovers the signer from them. Ethereum signs a Keccak-256 digest; this library takes digests and does not hash.
1.4 Encodings
The compact form is 64 bytes, r ‖ s as 32-byte big-endian integers; it leaves out a recoverable signature’s id, which is stored beside it. DER is the variable-length form Bitcoin uses, at most 72 bytes, and der->ecdsa-signature accepts strict DER only. Compact bytes of the right length that are not a signature, and bytes that are not strict DER, raise exn:fail:libsecp256k1:signature; compact bytes of another length are a contract violation.
> (define compact (ecdsa-signature->compact sig)) > (bytes-length compact) 64
> (equal? (compact->ecdsa-signature compact) sig) #t
> (equal? (compact->ecdsa-recoverable-signature (ecdsa-signature->compact rsig) (ecdsa-recoverable-signature-id rsig)) rsig) #t
> (define der (ecdsa-signature->der sig)) > (equal? (der->ecdsa-signature der) sig) #t
> (der->ecdsa-signature (bytes-append der #"\0"))
der->ecdsa-signature: invalid signature;
not strict DER, or r or s is negative or not less than the curve order
See "examples/03-encodings.rkt".
1.5 Tweaks
Adding a 32-byte tweak t to a secret key k gives k + t; adding it to the public key P gives P + tG, the public key of k + t. So whoever holds only a public key can compute the public keys of children whose secret keys only its owner can compute. A tweak not less than n, or a result that is zero or the point at infinity, raises exn:fail:libsecp256k1:key.
> (define tweak (sha256-bytes (bytes-append (public-key->bytes public) #"\0\0\0\0"))) > (define child (secret-key-tweak-add key tweak)) > (equal? (secret-key->public-key child) (public-key-tweak-add public tweak)) #t
> (public-key-combine public (public-key-negate public)) public-key-combine: the sum is the point at infinity
"examples/04-tweaks.rkt" derives numbered children from a parent key and from its public key, and checks that they agree.
2 Reference
2.1 Secret Keys
procedure
(secret-key? v) → boolean?
v : any/c
procedure
procedure
k : exact-integer?
procedure
(bytes->secret-key bs) → secret-key?
bs : secret-bytes/c
> (define one (integer->secret-key 1)) > one #<secret-key>
> (secret-key->integer one) 1
> (equal? one (integer->secret-key 1)) #f
> (integer->secret-key 0)
integer->secret-key: invalid secret key;
the value is less than 1 or not less than the curve order
procedure
key : secret-key/c
procedure
(secret-key->bytes key) → secret-bytes/c
key : secret-key/c
procedure
(secret-key->public-key key) → public-key?
key : secret-key/c
procedure
(secret-key-negate key) → secret-key?
key : secret-key/c
value
value
2.2 Public Keys
procedure
(public-key? v) → boolean?
v : any/c
procedure
(bytes->public-key bs) → public-key?
bs : public-key-bytes/c
procedure
(public-key->bytes key [ #:compressed? compressed?]) → public-key-bytes/c key : public-key? compressed? : any/c = #t
> (define pk (secret-key->public-key one)) > pk #<public-key 0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798>
> (bytes->hex-string (public-key->bytes pk #:compressed? #f)) "0479be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8"
> (equal? pk (bytes->public-key (public-key->bytes pk #:compressed? #f))) #t
procedure
(public-key-negate key) → public-key?
key : public-key?
procedure
(public-key-combine key ...+) → public-key?
key : public-key?
value
2.3 ECDSA Signatures
Arguments keep the C library’s order: the thing being signed or checked comes before the key.
value
value
value
procedure
(ecdsa-signature r s) → ecdsa-signature?
r : scalar/c s : scalar/c
procedure
(ecdsa-signature? v) → boolean?
v : any/c
procedure
(ecdsa-signature-r sig) → scalar/c
sig : ecdsa-signature?
procedure
(ecdsa-signature-s sig) → scalar/c
sig : ecdsa-signature?
procedure
(ecdsa-sign digest key) → ecdsa-signature?
digest : digest/c key : secret-key/c
> (define digest (sha256-bytes #"Satoshi Nakamoto")) > (define sig (ecdsa-sign digest one)) > sig #<ecdsa-signature 934b1ea10a4b3c1757e2b0c017d0b6143ce3c9a7e6a4a49860d7a6ab210ee3d82442ce9d2b916064108014783e923ec36b49743e2ffa1c4496f01a512aafd9e5>
> (ecdsa-verify sig digest pk) #t
procedure
(ecdsa-verify sig digest key) → boolean?
sig : ecdsa-signature? digest : digest/c key : public-key?
procedure
(ecdsa-signature-low-s? sig) → boolean?
sig : ecdsa-signature?
procedure
sig : ecdsa-signature?
> (define high (ecdsa-signature (ecdsa-signature-r sig) (- secp256k1-order (ecdsa-signature-s sig)))) > (ecdsa-verify high digest pk) #f
> (equal? (ecdsa-signature-normalize high) sig) #t
2.3.1 Encodings
Compact is r ‖ s as 32-byte big-endian integers; DER is strict. Parsing raises exn:fail:libsecp256k1:signature.
procedure
sig : ecdsa-signature?
procedure
bs : compact-bytes/c
procedure
(compact->ecdsa-recoverable-signature bs id) → ecdsa-recoverable-signature? bs : compact-bytes/c id : recovery-id/c
procedure
(ecdsa-signature->der sig) → der-bytes/c
sig : ecdsa-signature?
procedure
bs : bytes?
> (bytes->hex-string (ecdsa-signature->der sig)) "3045022100934b1ea10a4b3c1757e2b0c017d0b6143ce3c9a7e6a4a49860d7a6ab210ee3d802202442ce9d2b916064108014783e923ec36b49743e2ffa1c4496f01a512aafd9e5"
> (equal? (der->ecdsa-signature (ecdsa-signature->der sig)) sig) #t
value
value
2.3.2 Public Key Recovery
procedure
(ecdsa-recoverable-signature r s id)
→ ecdsa-recoverable-signature? r : scalar/c s : scalar/c id : recovery-id/c
procedure
v : any/c
procedure
sig : ecdsa-recoverable-signature?
procedure
(ecdsa-sign-recoverable digest key)
→ ecdsa-recoverable-signature? digest : digest/c key : secret-key/c
procedure
(ecdsa-recover sig digest) → (or/c public-key? #f)
sig : ecdsa-recoverable-signature? digest : digest/c
> (define rsig (ecdsa-sign-recoverable digest one)) > rsig #<ecdsa-recoverable-signature 934b1ea10a4b3c1757e2b0c017d0b6143ce3c9a7e6a4a49860d7a6ab210ee3d82442ce9d2b916064108014783e923ec36b49743e2ffa1c4496f01a512aafd9e5 id=1>
> (equal? (ecdsa-recover rsig digest) pk) #t
2.4 Tweaks
procedure
(secret-key-tweak-add key tweak) → secret-key?
key : secret-key/c tweak : secret-bytes/c
procedure
(public-key-tweak-add key tweak) → public-key?
key : public-key? tweak : secret-bytes/c
A tweak derived only from public data gives the parent’s secret key away to whoever holds a child’s secret key and that data: the parent’s key is the child’s minus the tweak.
> (define t (secret-key->bytes one)) > (secret-key->public-key (secret-key-tweak-add one t)) #<public-key 02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5>
> (equal? (public-key-tweak-add pk t) (secret-key->public-key (secret-key-tweak-add one t))) #t
2.5 Errors
Contract violations are ordinary exn:fail:contract:blame errors.
struct
struct
2.6 The C Library
procedure
(libsecp256k1-origin) → (or/c 'bundled 'system 'environment)
Every procedure may be called from any thread or place. Each call into the C library is atomic: no other Racket thread in the place runs until it returns, so a long batch of calls lets other threads run only between calls.