Add user functions comments

Author: abderraouf-adjal

README.txt

@@ -22,7 +22,7 @@ spritz_t - Contain the state.
 
 * Functions
 setup()   - To setup spritz state (spritz_t).
-setupIV() - Usable after setup() to add Nonce.
+setupIV() - Usable after setup() to add Nonce (Salt).
 stream()  - Return random byte that can be used as a key.
 hash()    - Hash function.
 mac()     - Message Authentication Code (MAC) function.

SpritzCipher.cpp

@@ -118,13 +118,11 @@ void SpritzCipher::absorbNibble(spritz_t *ctx, const byte nibble)
   swap(&ctx->s[ctx->a], &ctx->s[SPRITZ_N_HALF + nibble]);
   ctx->a++;
 }
-
 void SpritzCipher::absorb(spritz_t *ctx, const byte octet)
 {
   absorbNibble(ctx, octet % 16); /* Low */
   absorbNibble(ctx, octet / 16); /* High */
 }
-
 void SpritzCipher::absorbBytes(spritz_t *ctx, const byte *buf, unsigned int len)
 {
   unsigned int i;
@@ -169,28 +167,40 @@ void SpritzCipher::squeeze(spritz_t *ctx, byte *out, byte len)
 }
 
 
+/**************************| USER FUNCTIONS |**************************/
 
+/* Setup spritz state (spritz_t) */
 void SpritzCipher::setup(spritz_t *ctx,
                          const byte *key, unsigned int keyLen)
 {
   stateInit(ctx);
   absorbBytes(ctx, key, keyLen);
 }
 
-/* Use setupIV() after setup() to add NONCE */
+/* Use setupIV() *after* setup() to add NONCE (Salt) */
 void SpritzCipher::setupIV(spritz_t *ctx,
                            const byte *nonce, unsigned int nonceLen)
 {
   absorbStop(ctx);
   absorbBytes(ctx, nonce, nonceLen);
 }
 
+/* Return random byte that can be used as a key */
 byte SpritzCipher::stream(spritz_t *ctx)
 {
   return drip(ctx);
 }
 
 
+/**
+ * Cryptographic hash function
+ * 
+ * - digest: Hash output.
+ * - digestLen: Set hash output size, Value (>=) 32 is recommended.
+ * 
+ * - data: Data to hash.
+ * - dataLen: Data size.
+ */
 void SpritzCipher::hash(byte *digest, byte digestLen,
                         const byte *data, unsigned int dataLen)
 {
@@ -202,6 +212,18 @@ void SpritzCipher::hash(byte *digest, byte digestLen,
   squeeze(&ctx, digest, digestLen);
 }
 
+/**
+ * Message Authentication Code (MAC) function
+ * 
+ * - digest: MAC output.
+ * - digestLen: Set MAC output size, Value (>=) 32 is recommended.
+ * 
+ * - msg: Message to be authenticated.
+ * - msgLen: Message size.
+ * 
+ * - key: The secret key.
+ * - keyLen: The secret key size.
+ */
 void SpritzCipher::mac(byte *digest, byte digestLen,
                        const byte *msg, unsigned int msgLen,
                        const byte *key, unsigned int keyLen)

SpritzCipher.h

@@ -42,18 +42,45 @@ class SpritzCipher
   public:
     SpritzCipher();
 
+    /* Setup spritz state (spritz_t) */
     void setup(spritz_t *ctx,
                const byte *key, unsigned int keyLen);
+
+    /* Use setupIV() *after* setup() to add NONCE (Salt) */
     void setupIV(spritz_t *ctx,
                  const byte *nonce, unsigned int nonceLen);
+
+    /* Return random byte that can be used as a key */
     byte stream(spritz_t *ctx);
 
+    /**
+     * Cryptographic hash function
+     * 
+     * - digest: Hash output.
+     * - digestLen: Set hash output size, Value (>=) 32 is recommended.
+     * 
+     * - data: Data to hash.
+     * - dataLen: Data size.
+     */
     void hash(byte *digest, byte digestLen,
               const byte *data, unsigned int dataLen);
+    /**
+     * Message Authentication Code (MAC) function
+     * 
+     * - digest: MAC output.
+     * - digestLen: Set MAC output size, Value (>=) 32 is recommended.
+     * 
+     * - msg: Message to be authenticated.
+     * - msgLen: Message size.
+     * 
+     * - key: The secret key.
+     * - keyLen: The secret key size.
+     */
     void mac(byte *digest, byte digestLen,
              const byte *msg, unsigned int msgLen,
              const byte *key, unsigned int keyLen);
 
+
   private:
     void swap(byte *a, byte *b);
     void stateInit(spritz_t *ctx);