public interface docs

include/secp256k1.h

@@ -5,9 +5,45 @@
 extern "C" {
 #endif
 
+/** Initialize the library. This may take some time (10-100 ms).
+ *  You need to call this before calling any other function.
+ *  It cannot run in parallel with any other functions, but once
+ *  secp256k1_start() returns, all other functions are thread-safe.
+ */
 void secp256k1_start(void);
+
+/** Free all memory associated with this library. After this, no
+ *  functions can be called anymore, except secp256k1_start()
+ */
 void secp256k1_stop(void);
-int secp256k1_ecdsa_verify(const unsigned char *msg, int msglen, const unsigned char *sig, int siglen, const unsigned char *pubkey, int pubkeylen);
+
+/** Verify an ECDSA signature.
+ *  Returns: 1: correct signature
+ *           0: incorrect signature
+ *          -1: invalid public key
+ *          -2: invalid signature
+ */
+int secp256k1_ecdsa_verify(const unsigned char *msg, int msglen,
+                           const unsigned char *sig, int siglen,
+                           const unsigned char *pubkey, int pubkeylen);
+
+/** Just validate a public key.
+ *  Returns: 1: valid public key
+ *           0: invalid public key
+ */
+/* NOT YET IMPLEMENTED */
+int secp256k1_ecdsa_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.
+ *  Out:    pubkey:     pointer to a 33-byte (if compressed) or 65-byte (if uncompressed)
+ *                      area to store the public key.
+ *  Returns: 1: secret was valid, public key stores
+ *           0: secret was invalid, try again.
+ */
+/* NOT YET IMPLEMENTED */
+int secp256k1_ecdsa_pubkey_create(unsigned char *pubkey, int compressed, const unsigned char *seckey)
 
 #ifdef __cplusplus
 }