From c27fdc0b97edc57d1d5c4f135d90ad3d2eafee9e Mon Sep 17 00:00:00 2001 From: Pieter Wuille Date: Tue, 11 Nov 2014 15:21:47 -0800 Subject: [PATCH] Document some preconditions --- include/secp256k1.h | 59 ++++++++++++++++++++++++++------------------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/include/secp256k1.h b/include/secp256k1.h index cb5fd3c..4a468e0 100644 --- a/include/secp256k1.h +++ b/include/secp256k1.h @@ -26,6 +26,12 @@ void secp256k1_stop(void); * 0: incorrect signature * -1: invalid public key * -2: invalid signature + * In: msg: the message being verified (cannot be NULL) + * msglen: the length of the message (at most 32) + * sig: the signature being verified (cannot be NULL) + * siglen: the length of the signature + * pubkey: the public key to verify with (cannot be NULL) + * pubkeylen: the length of pubkey * Requires starting using SECP256K1_START_VERIFY. */ int secp256k1_ecdsa_verify(const unsigned char *msg, int msglen, @@ -35,12 +41,13 @@ int secp256k1_ecdsa_verify(const unsigned char *msg, int msglen, /** Create an ECDSA signature. * Returns: 1: signature created * 0: nonce invalid, try another one - * In: msg: the message being signed - * msglen: the length of the message being signed - * seckey: pointer to a 32-byte secret key (assumed to be valid) - * nonce: pointer to a 32-byte nonce (generated with a cryptographic PRNG) - * Out: sig: pointer to a 72-byte array where the signature will be placed. - * siglen: pointer to an int, which will be updated to the signature length (<=72). + * In: msg: the message being signed (cannot be NULL) + * msglen: the length of the message being signed (at most 32) + * seckey: pointer to a 32-byte secret key (cannot be NULL, assumed to be valid) + * nonce: pointer to a 32-byte nonce (cannot be NULL, generated with a cryptographic PRNG) + * Out: sig: pointer to an array where the signature will be placed (cannot be NULL) + * In/Out: siglen: pointer to an int with the length of sig, which will be updated + * to contain the actual signature length (<=72). * Requires starting using SECP256K1_START_SIGN. */ int secp256k1_ecdsa_sign(const unsigned char *msg, int msglen, @@ -51,12 +58,12 @@ int secp256k1_ecdsa_sign(const unsigned char *msg, int msglen, /** Create a compact ECDSA signature (64 byte + recovery id). * Returns: 1: signature created * 0: nonce invalid, try another one - * In: msg: the message being signed - * msglen: the length of the message being signed - * seckey: pointer to a 32-byte secret key (assumed to be valid) - * nonce: pointer to a 32-byte nonce (generated with a cryptographic PRNG) - * Out: sig: pointer to a 64-byte array where the signature will be placed. - * recid: pointer to an int, which will be updated to contain the recovery id. + * In: msg: the message being signed (cannot be NULL) + * msglen: the length of the message being signed (at most 32) + * seckey: pointer to a 32-byte secret key (cannot be NULL, assumed to be valid) + * nonce: pointer to a 32-byte nonce (cannot be NULL, generated with a cryptographic PRNG) + * Out: sig: pointer to a 64-byte array where the signature will be placed (cannot be NULL) + * recid: pointer to an int, which will be updated to contain the recovery id (can be NULL) * Requires starting using SECP256K1_START_SIGN. */ int secp256k1_ecdsa_sign_compact(const unsigned char *msg, int msglen, @@ -66,15 +73,15 @@ int secp256k1_ecdsa_sign_compact(const unsigned char *msg, int msglen, int *recid); /** Recover an ECDSA public key from a compact signature. - * Returns: 1: public key succesfully recovered (which guarantees a correct signature). + * Returns: 1: public key successfully recovered (which guarantees a correct signature). * 0: otherwise. - * In: msg: the message assumed to be signed - * msglen: the length of the message - * sig64: signature as 64 byte array + * In: msg: the message assumed to be signed (cannot be NULL) + * msglen: the length of the message (at most 32) + * sig64: signature as 64 byte array (cannot be NULL) * compressed: whether to recover a compressed or uncompressed pubkey - * recid: the recovery id (as returned by ecdsa_sign_compact) - * Out: pubkey: pointer to a 33 or 65 byte array to put the pubkey. - * pubkeylen: pointer to an int that will contain the pubkey length. + * recid: the recovery id (0-3, as returned by ecdsa_sign_compact) + * Out: pubkey: pointer to a 33 or 65 byte array to put the pubkey (cannot be NULL) + * pubkeylen: pointer to an int that will contain the pubkey length (cannot be NULL) * Requires starting using SECP256K1_START_VERIFY. */ int secp256k1_ecdsa_recover_compact(const unsigned char *msg, int msglen, @@ -85,23 +92,25 @@ int secp256k1_ecdsa_recover_compact(const unsigned char *msg, int msglen, /** Verify an ECDSA secret key. * Returns: 1: secret key is valid * 0: secret key is invalid - * In: seckey: pointer to a 32-byte secret key + * In: seckey: pointer to a 32-byte secret key (cannot be NULL) */ int secp256k1_ec_seckey_verify(const unsigned char *seckey); /** Just validate a public key. * Returns: 1: valid public key * 0: invalid public key + * In: pubkey: pointer to a 33-byte or 65-byte public key (cannot be NULL). + * pubkeylen: length of pubkey */ int secp256k1_ec_pubkey_verify(const unsigned char *pubkey, int pubkeylen); /** Compute the public key for a secret key. * In: compressed: whether the computed public key should be compressed - * seckey: pointer to a 32-byte private key. + * seckey: pointer to a 32-byte private key (cannot be NULL) * Out: pubkey: pointer to a 33-byte (if compressed) or 65-byte (if uncompressed) - * area to store the public key. + * area to store the public key (cannot be NULL) * pubkeylen: pointer to int that will be updated to contains the pubkey's - * length. + * length (cannot be NULL) * Returns: 1: secret was valid, public key stores * 0: secret was invalid, try again. * Requires starting using SECP256K1_START_SIGN. @@ -110,8 +119,8 @@ int secp256k1_ec_pubkey_create(unsigned char *pubkey, int *pubkeylen, const unsi /** Decompress a public key. * In/Out: pubkey: pointer to a 65-byte array to put the decompressed public key. - It must contain a 33-byte or 65-byte public key already. - * pubkeylen: pointer to the size of the public key pointed to be pubkey. + It must contain a 33-byte or 65-byte public key already (cannot be NULL) + * pubkeylen: pointer to the size of the public key pointed to by pubkey (cannot be NULL) It will be updated to reflect the new size. * Returns: 0 if the passed public key was invalid, 1 otherwise. If 1 is returned, the pubkey is replaced with its decompressed version.