Update auth.c demo description.

demos/auth.c

@@ -11,9 +11,27 @@
 #include "utils.h" /* utility functions shared by demos */
 
 /*
- * Full featured authentication which is used to verify that the message
- * comes from the expected person. It should be safe to keep the same key
- * for multiple messages.
+ * This operation computes an authentication tag for a message and a
+ * secret key, and provides a way to verify that a given tag is valid
+ * for a given message and a key.
+ *
+ * The function computing the tag deterministic: the same (message,
+ * key) tuple will always produce the same output.
+ *
+ * However, even if the message is public, knowing the key is
+ * required in order to be able to compute a valid tag. Therefore,
+ * the key should remain confidential. The tag, however, can be
+ * public.
+ *
+ * A typical use case is:
+ *
+ * - A prepares a message, add an authentication tag, sends it to B
+ * - A doesn't store the message
+ * - Later on, B sends the message and the authentication tag to A
+ * - A uses the authentication tag to verify that it created this message.
+ *
+ * This operation does not encrypt the message. It only computes and
+ * verifies an authentication tag.
  */
 static int
 auth(void)
@@ -50,8 +68,6 @@ auth(void)
     print_verification(ret);
 
     sodium_memzero(key, sizeof key); /* wipe sensitive data */
-    sodium_memzero(mac, sizeof mac);
-    sodium_memzero(message, sizeof message);
 
     return ret;
 }