Improve header docs

include/tabby.h

@@ -213,54 +213,84 @@ extern int tabby_verify(const void *message, int bytes, const char public_key[64
  * The resulting 80-byte verifier value should be stored in the user database,
  * so that the server can verify this password during login.
  *
- * The 'client_secret' parameter can be set to null if it is not needed.
- *
  * Returns 0 on success.
  * Returns non-zero if the input data is invalid.
  */
-extern int tabby_password(tabby_client *C, const void *username, int username_len, const void *realm, int realm_len, const void *password, int password_len, char password_verifier[80]);
+extern int tabby_password(
+		tabby_client *C,
+		const void *username, int username_len,
+		const void *realm, int realm_len,
+		const void *password, int password_len,
+		char password_verifier[80]);
 
 /*
  * Generate a password challenge
  *
  * The challenge should be sent to the client attempting to login.  And the
- * challenge secret should be stored to validate the client's response.
+ * challenge secret should be stored to validate the client's response.  Do not
+ * send the secret to the client.
+ *
+ * The challenge and all the other password-related messages should ideally be
+ * sent encrypted (using e.g. Calico) inside a secure tunnel created with the
+ * Tabby handshake.
  *
  * Returns 0 on success.
  * Returns non-zero if the input data is invalid.
  */
-extern int tabby_password_challenge(tabby_server *S, const char password_verifier[80], char challenge_secret[288], char challenge[80]);
+extern int tabby_password_challenge(
+		tabby_server *S,
+		const char password_verifier[80],
+		char challenge_secret[288], char challenge[80]);
 
 /*
  * Respond to a password challenge from server
  *
  * The client_proof is sent by a client after the server has challenged them.
  *
+ * If the function fails, then the client should disconnect immediately.
+ *
  * Returns 0 on success.
  * Returns non-zero if the server's challenge was invalid.
  */
-extern int tabby_password_client_proof(tabby_client *C, const void *username, int username_len, const void *realm, int realm_len, const void *password, int password_len, const char challenge[80], const char server_public[64], char server_verifier[32], char client_proof[96]);
+extern int tabby_password_client_proof(
+		tabby_client *C,
+		const void *username, int username_len,
+		const void *realm, int realm_len,
+		const void *password, int password_len,
+		const char challenge[80], // message from server
+		const char server_public[64], // server public key
+		char server_verifier[32], char client_proof[96]);
 
 /*
  * Respond to a password proof from client
  *
  * The server_proof is sent by a server after the client has provided proof.
  *
+ * If the function fails, then the client provided the wrong password.
+ *
  * Returns 0 on success.
  * Returns non-zero if the client's proof was invalid.
  */
-extern int tabby_password_server_proof(tabby_server *S, const char client_proof[96], const char challenge_secret[288], char server_proof[32]);
+extern int tabby_password_server_proof(
+		tabby_server *S,
+		const char client_proof[96], // message from client
+		const char challenge_secret[288], // stored challenge secret
+		char server_proof[32]);
 
 /*
  * Verify a password proof from server
  *
  * This actually just compares to make sure the two values are the same, but it
- * does this in constant-time.
+ * does the comparison in constant-time.
+ *
+ * If the function fails, then the client should disconnect immediately.
  *
  * Returns 0 on success.
  * Returns non-zero if the client's proof was invalid.
  */
-extern int tabby_password_check_server(const char server_verifier[32], const char server_proof[32]);
+extern int tabby_password_check_server(
+		const char server_verifier[32],
+		const char server_proof[32]);
 
 
 //// Cleanup

tabby-mobile/tabby.h

@@ -213,54 +213,84 @@ extern int tabby_verify(const void *message, int bytes, const char public_key[64
  * The resulting 80-byte verifier value should be stored in the user database,
  * so that the server can verify this password during login.
  *
- * The 'client_secret' parameter can be set to null if it is not needed.
- *
  * Returns 0 on success.
  * Returns non-zero if the input data is invalid.
  */
-extern int tabby_password(tabby_client *C, const void *username, int username_len, const void *realm, int realm_len, const void *password, int password_len, char password_verifier[80]);
+extern int tabby_password(
+		tabby_client *C,
+		const void *username, int username_len,
+		const void *realm, int realm_len,
+		const void *password, int password_len,
+		char password_verifier[80]);
 
 /*
  * Generate a password challenge
  *
  * The challenge should be sent to the client attempting to login.  And the
- * challenge secret should be stored to validate the client's response.
+ * challenge secret should be stored to validate the client's response.  Do not
+ * send the secret to the client.
+ *
+ * The challenge and all the other password-related messages should ideally be
+ * sent encrypted (using e.g. Calico) inside a secure tunnel created with the
+ * Tabby handshake.
  *
  * Returns 0 on success.
  * Returns non-zero if the input data is invalid.
  */
-extern int tabby_password_challenge(tabby_server *S, const char password_verifier[80], char challenge_secret[288], char challenge[80]);
+extern int tabby_password_challenge(
+		tabby_server *S,
+		const char password_verifier[80],
+		char challenge_secret[288], char challenge[80]);
 
 /*
  * Respond to a password challenge from server
  *
  * The client_proof is sent by a client after the server has challenged them.
  *
+ * If the function fails, then the client should disconnect immediately.
+ *
  * Returns 0 on success.
  * Returns non-zero if the server's challenge was invalid.
  */
-extern int tabby_password_client_proof(tabby_client *C, const void *username, int username_len, const void *realm, int realm_len, const void *password, int password_len, const char challenge[80], const char server_public[64], char server_verifier[32], char client_proof[96]);
+extern int tabby_password_client_proof(
+		tabby_client *C,
+		const void *username, int username_len,
+		const void *realm, int realm_len,
+		const void *password, int password_len,
+		const char challenge[80], // message from server
+		const char server_public[64], // server public key
+		char server_verifier[32], char client_proof[96]);
 
 /*
  * Respond to a password proof from client
  *
  * The server_proof is sent by a server after the client has provided proof.
  *
+ * If the function fails, then the client provided the wrong password.
+ *
  * Returns 0 on success.
  * Returns non-zero if the client's proof was invalid.
  */
-extern int tabby_password_server_proof(tabby_server *S, const char client_proof[96], const char challenge_secret[288], char server_proof[32]);
+extern int tabby_password_server_proof(
+		tabby_server *S,
+		const char client_proof[96], // message from client
+		const char challenge_secret[288], // stored challenge secret
+		char server_proof[32]);
 
 /*
  * Verify a password proof from server
  *
  * This actually just compares to make sure the two values are the same, but it
- * does this in constant-time.
+ * does the comparison in constant-time.
+ *
+ * If the function fails, then the client should disconnect immediately.
  *
  * Returns 0 on success.
  * Returns non-zero if the client's proof was invalid.
  */
-extern int tabby_password_check_server(const char server_verifier[32], const char server_proof[32]);
+extern int tabby_password_check_server(
+		const char server_verifier[32],
+		const char server_proof[32]);
 
 
 //// Cleanup