From dc4a9791a724961be5729c0750807efa67fd42d9 Mon Sep 17 00:00:00 2001
From: Frank Denis <github@pureftpd.org>
Date: Fri, 22 Jan 2016 16:12:24 +0100
Subject: [PATCH] Add comments to argon2-encoding.c Upstream `decode_string()`
 can return `ARGON2_INCORRECT_TYPE`. This change is not merged. Either have a
 function return an ARGON2 constant, have it return 0/1, or have it return
 0/-1, but mixing different systems is confusing. (encode|decode)_string()
 should probably all return an ARGON2 code.

---
 .../crypto_pwhash/argon2/argon2-encoding.c    | 14 ++++++++-----
 .../crypto_pwhash/argon2/argon2-encoding.h    | 21 +++++++++++++++++++
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/src/libsodium/crypto_pwhash/argon2/argon2-encoding.c b/src/libsodium/crypto_pwhash/argon2/argon2-encoding.c
index 56933893..6bac5852 100644
--- a/src/libsodium/crypto_pwhash/argon2/argon2-encoding.c
+++ b/src/libsodium/crypto_pwhash/argon2/argon2-encoding.c
@@ -6,7 +6,7 @@
 #include "argon2-encoding.h"
 
 /*
- * Example code for a decoder and encoder of "hash strings", with Argon2i
+ * Example code for a decoder and encoder of "hash strings", with Argon2
  * parameters.
  *
  * This code comprises three sections:
@@ -18,7 +18,7 @@
  *   the relevant functions are made public (non-static) and be given
  *   reasonable names to avoid collisions with other functions.
  *
- *   -- The second section is specific to Argon2i. It encodes and decodes
+ *   -- The second section is specific to Argon2. It encodes and decodes
  *   the parameters, salts and outputs. It does not compute the hash
  *   itself.
  *
@@ -225,13 +225,13 @@ static const char *decode_decimal(const char *str, unsigned long *v) {
 
 /* ==================================================================== */
 /*
- * Code specific to Argon2i.
+ * Code specific to Argon2.
  *
  * The code below applies the following format:
  *
- *  $argon2i$m=<num>,t=<num>,p=<num>[,keyid=<bin>][,data=<bin>][$<bin>[$<bin>]]
+ *  $argon2<T>$m=<num>,t=<num>,p=<num>[,keyid=<bin>][,data=<bin>][$<bin>[$<bin>]]
  *
- * where <num> is a decimal integer (positive, fits in an 'unsigned long')
+ * where <T> is either 'd' or 'i', <num> is a decimal integer (positive, fits in an 'unsigned long')
  * and <bin> is Base64-encoded data (no '=' padding characters, no newline
  * or whitespace). The "keyid" is a binary identifier for a key (up to 8
  * bytes); "data" is associated data (up to 32 bytes). When the 'keyid'
@@ -248,6 +248,7 @@ static const char *decode_decimal(const char *str, unsigned long *v) {
  * Returned value is 1 on success, 0 on error.
  */
 int decode_string(argon2_context *ctx, const char *str, argon2_type type) {
+    /* check for prefix */
 #define CC(prefix)                                                             \
     do {                                                                       \
         size_t cc_len = strlen(prefix);                                        \
@@ -257,6 +258,7 @@ int decode_string(argon2_context *ctx, const char *str, argon2_type type) {
         str += cc_len;                                                         \
     } while ((void)0, 0)
 
+    /* prefix checking with supplied code */
 #define CC_opt(prefix, code)                                                   \
     do {                                                                       \
         size_t cc_len = strlen(prefix);                                        \
@@ -266,6 +268,7 @@ int decode_string(argon2_context *ctx, const char *str, argon2_type type) {
         }                                                                      \
     } while ((void)0, 0)
 
+    /* Decoding prefix into decimal */
 #define DECIMAL(x)                                                             \
     do {                                                                       \
         unsigned long dec_x;                                                   \
@@ -276,6 +279,7 @@ int decode_string(argon2_context *ctx, const char *str, argon2_type type) {
         (x) = dec_x;                                                           \
     } while ((void)0, 0)
 
+    /* Decoding prefix into binary */
 #define BIN(buf, max_len, len)                                                 \
     do {                                                                       \
         size_t bin_len = (max_len);                                            \
diff --git a/src/libsodium/crypto_pwhash/argon2/argon2-encoding.h b/src/libsodium/crypto_pwhash/argon2/argon2-encoding.h
index f1a1545a..46d4b47e 100644
--- a/src/libsodium/crypto_pwhash/argon2/argon2-encoding.h
+++ b/src/libsodium/crypto_pwhash/argon2/argon2-encoding.h
@@ -3,9 +3,30 @@
 
 #include "argon2.h"
 
+/*
+ * encode an Argon2 hash string into the provided buffer. 'dst_len'
+ * contains the size, in characters, of the 'dst' buffer; if 'dst_len'
+ * is less than the number of required characters (including the
+ * terminating 0), then this function returns 0.
+ *
+ * if ctx->outlen is 0, then the hash string will be a salt string
+ * (no output). if ctx->saltlen is also 0, then the string will be a
+ * parameter-only string (no salt and no output).
+ *
+ * On success, 1 is returned.
+ *
+ * No other parameters are checked
+ */
 int encode_string(char *dst, size_t dst_len, argon2_context *ctx,
                   argon2_type type);
 
+/*
+ * Decodes an Argon2 hash string into the provided structure 'ctx'.
+ * The fields ctx.saltlen, ctx.adlen, ctx.outlen set the maximal salt, ad, out length values
+ * that are allowed; invalid input string causes an error
+ *
+ * Returned value is 1 on success, 0 on error.
+ */
 int decode_string(argon2_context *ctx, const char *str, argon2_type type);
 
 #endif