<p>This was discussed before a <a href="https://bitcoincore.reviews/libsecp256k1-748" rel="nofollow noreferrer">PR review club</a> on secp256k1 <a href="https://github.com/bitcoin-core/secp256k1/pull/748" rel="nofollow noreferrer">usage examples</a> on February 2nd 2022. Thanks to the individuals (glozow, lightlike, sipa, robot-dreams etc) who answered this. I haven't made any substantial changes but any errors are my own.</p>
<p>A function that isn't exposed in the <a href="https://github.com/bitcoin-core/secp256k1/tree/master/include" rel="nofollow noreferrer">header files</a> is not visible to a prospective caller. The repo is open source so it can be forked with additional functions added to the header files but then you have to maintain a fork and upgrading will be a pain (no one upstream will care about keeping the interface of internal functions stable).</p>
<p>However, just adding a function to a header file isn't enough. The build will fail at linking time if you add a function to a header without also modifying the library to provide and export such a function. The header tells callers how they can call exported library functions. If the header and the exported library functions mismatch you'll get an error. You'll also need to modify the library to export these functions.</p>
<p>To the extent that doing this is advisable or not depends on the use case, capability of the developer and willingness to maintain a fork of the repo. Generally it is recommended that you don't &quot;roll your own crypto&quot; unless you know what you are doing. There are many pitfalls the more ambitious the changes are.</p>
<p>The Bitcoin Core repo uses the secp256k1 API in various ways. For ECDSA the caller provides the message hash to libsecp256k1 and it signs/verifies. For BIP 340 (Schnorr) the caller provides the message and libsecp256k1 does the hashing.</p>
<p>libsecp256k1 only has a very simple unoptimized implementation of the SHA256 hash function so it can do RFC6979. There have been discussions on allowing callers to provide their own SHA256 implementation to the library or adding a new API function that takes an unhashed message and returns the hash. However, Bitcoin uses double SHA256 to obtain the message hash and so that would either not match Bitcoin's usage of ECDSA or still require the caller to do one of two hashing steps (or not be standard).</p>
<p>There is an issue discussing how an external project can use the secp256k1 library <a href="https://github.com/bitcoin-core/secp256k1/issues/224" rel="nofollow noreferrer">here</a>.</p>

CC BY-SA 4.0
2022-02-03T17:16:16.420Z
2022-04-03T13:11:21.717Z
2022-04-03T13:11:21.717Z
Michael Folkson
<p>I'm familiar with proprietary APIs where a third party decides what data and functionality is available to developers communicating with their server.</p>
<p>However, secp256k1 is an open source cryptographic library which is entirely accessible/callable and can be forked. What is the secp256k1 API in this case and in what ways is it restricted to limit functionality?</p>
<p>In this <a href="https://github.com/bitcoin-core/secp256k1/issues/184#issue-53981864" rel="nofollow noreferrer">GitHub comment</a> it is suggested that people back in 2015 were &quot;attempting to use the library calling into random internal functions. That should be harder to do now&quot;. Why is this discouraged and why is it harder to do now?</p>

<api><bitcoin-core-development><secp256k1>
How is the secp256k1 API defined? In what ways is it restricted?
Michael Folkson
# How is the secp256k1 API defined? In what ways is it restricted?

(Asked by: username_0 on 2022-02-03)

I'm familiar with proprietary APIs where a third party decides what data and functionality is available to developers communicating with their server.

However, secp256k1 is an open source cryptographic library which is entirely accessible/callable and can be forked. What is the secp256k1 API in this case and in what ways is it restricted to limit functionality?

In this [GitHub comment](https://github.com/bitcoin-core/secp256k1/issues/184#issue-53981864) it is suggested that people back in 2015 were "attempting to use the library calling into random internal functions. That should be harder to do now". Why is this discouraged and why is it harder to do now?

**Tags:** api, bitcoin-core-development, secp256k1


---

## 1 answers

### Answer by username_0 on 2022-02-03. Score: 1 | Accepted answer

This was discussed before a [PR review club](https://bitcoincore.reviews/libsecp256k1-748) on secp256k1 [usage examples](https://github.com/bitcoin-core/secp256k1/pull/748) on February 2nd 2022. Thanks to the individuals (glozow, lightlike, sipa, robot-dreams etc) who answered this. I haven't made any substantial changes but any errors are my own.

A function that isn't exposed in the [header files](https://github.com/bitcoin-core/secp256k1/tree/master/include) is not visible to a prospective caller. The repo is open source so it can be forked with additional functions added to the header files but then you have to maintain a fork and upgrading will be a pain (no one upstream will care about keeping the interface of internal functions stable).

However, just adding a function to a header file isn't enough. The build will fail at linking time if you add a function to a header without also modifying the library to provide and export such a function. The header tells callers how they can call exported library functions. If the header and the exported library functions mismatch you'll get an error. You'll also need to modify the library to export these functions.

To the extent that doing this is advisable or not depends on the use case, capability of the developer and willingness to maintain a fork of the repo. Generally it is recommended that you don't "roll your own crypto" unless you know what you are doing. There are many pitfalls the more ambitious the changes are.

The Bitcoin Core repo uses the secp256k1 API in various ways. For ECDSA the caller provides the message hash to libsecp256k1 and it signs/verifies. For BIP 340 (Schnorr) the caller provides the message and libsecp256k1 does the hashing.

libsecp256k1 only has a very simple unoptimized implementation of the SHA256 hash function so it can do RFC6979. There have been discussions on allowing callers to provide their own SHA256 implementation to the library or adding a new API function that takes an unhashed message and returns the hash. However, Bitcoin uses double SHA256 to obtain the message hash and so that would either not match Bitcoin's usage of ECDSA or still require the caller to do one of two hashing steps (or not be standard).

There is an issue discussing how an external project can use the secp256k1 library [here](https://github.com/bitcoin-core/secp256k1/issues/224).


---

