frost/secp256k1-zkp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge bitcoin-core/secp256k1#783: Make the public API docs more consistent and explicit

Browse Source 
adec5a1638 Add missing null check for ctx and input keys in the public API (Elichai Turkel)
f4edfc7581 Improve consistency for NULL arguments in the public interface (Elichai Turkel)

Pull request description:

  I went over the public API and added missing explanations on when a pointer can be null and when it cannot,
  and added some missing checks for null ctx and null pubkey pointers.

  Open questions IMHO:
  1. Can `secp256k1_context_create` return NULL? right now it could return null if you replaced the callbacks at compile time to ones that do return(unlike the default ones which never return).
  2. Related to the first, should we document that the callbacks should never return? (in the tests we use returning callbacks but we can violate our own API) right now we say the following:

  > After this callback returns, anything may happen, including crashing.

  Is this enough to document answer `no` for the first question and just saying that if the callback returned then you violated the API so `secp256k1_context_create` can return NULL even though it is promised not to?
  Right now we AFAICT we never check if it returns null

  Another nit I'm not sure about is wording `(does nothing if NULL)`/`(ignored if NULL)`/`(can be NULL)`

  More missing docs:
  1. Documenting the `data` argument to the default nonce functions

ACKs for top commit:
  ariard:
    ACK adec5a16
  jonasnick:
    ACK adec5a1638

Tree-SHA512: 6fe785776b7e451e9e8cae944987f927b1eb2e2d404dfcb1b0ceb0a30bda4ce16469708920269417e5ada09739723a430e270dea1868fe7d12ccd5699dde5976
This commit is contained in:
Tim Ruffing
2021-09-15 16:23:55 +02:00
parent 9a5a87e0f1 adec5a1638
commit aa5d34a8fe
8 changed files with 125 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
include/secp256k1_schnorrsig.h
View File

@@ -106,10 +106,10 @@ typedef struct {
* signatures from being valid in multiple contexts by accident.
*
* Returns 1 on success, 0 on failure.
* Args: ctx: pointer to a context object, initialized for signing (cannot be NULL)
* Out: sig64: pointer to a 64-byte array to store the serialized signature (cannot be NULL)
* In: msg32: the 32-byte message being signed (cannot be NULL)
* keypair: pointer to an initialized keypair (cannot be NULL)
* Args: ctx: pointer to a context object, initialized for signing.
* Out: sig64: pointer to a 64-byte array to store the serialized signature.
* In: msg32: the 32-byte message being signed.
* keypair: pointer to an initialized keypair.
* aux_rand32: 32 bytes of fresh randomness. While recommended to provide
* this, it is only supplemental to security and can be NULL. See
* BIP-340 "Default Signing" for a full explanation of this
@@ -150,7 +150,7 @@ SECP256K1_API int secp256k1_schnorrsig_sign_custom(
* Returns: 1: correct signature
* 0: incorrect signature
* Args: ctx: a secp256k1 context object, initialized for verification.
* In: sig64: pointer to the 64-byte signature to verify (cannot be NULL)
* In: sig64: pointer to the 64-byte signature to verify.
* msg: the message being verified. Can only be NULL if msglen is 0.
* msglen: length of the message
* pubkey: pointer to an x-only public key to verify with (cannot be NULL)