Merge pull request #332 from libtom/sosemanuk--cleanup-comments-and-doc

sosemanuk updated comments and doc

doc/crypt.tex

@@ -1354,42 +1354,42 @@ Cree Indian language.)
 Sosemanuk will accept a key between 1 and 256 bits, but Sosemanuk's security level of 128
 bits is achieved only if the key is between 128 and 256 bits.  Keys longer than 128 bits
 are not guaranteed to provided higher security.  The initialization vector is 128 bits.
+(All length arguments are expressed in bytes.)
 
 See \url{http://www.ecrypt.eu.org/stream/p3ciphers/sosemanuk/sosemanuk_p3.pdf} for more
 information.
 
-You begin initializing Sosemanuk by creating a key context using a 128- to 256-bit key.
+Initialize by creating a Sosemanuk state and provide a 128- to 256-bit key to \textit{sosemanuk\_setup()}.
 \begin{verbatim}
-sosemanuk_key_context kc;
-err = sosemanuk_schedule(&kc, key, key_len);
+sosemanuk_state ss;
+err = sosemanuk_setup(&ss, key, keylen);
 \end{verbatim}
 
-Use the key context to create a run context and finish initialization with a 128-bit iv.
+Finish initializing with an iv of up to 128 bits.
 \begin{verbatim}
-sosemanuk_run_context rc;
-err = sosemanuk_init(&rc, &kc, iv, iv_len);
+err = sosemanuk_setiv(&ss, iv, ivlen);
 \end{verbatim}
 
 For the actual encryption or decryption, call:
 \begin{verbatim}
-err = sosemanuk_crypt(&rc, in_buffer, in_len, out_buffer);
+err = sosemanuk_crypt(&ss, in, inlen, out);
 \end{verbatim}
 
-If you just want a random stream of bytes initialize the cipher with a truly random \textit{key}
-(32 bytes), a truly random \textit{iv} (16 bytes). After that you can
+If you just want a random stream of bytes initialize the cipher with a truly random
+\textit{key} (256 bits) and a truly random \textit{iv} (128 bits). After that you can
 get a stream of pseudo--random bytes via:
 \begin{verbatim}
-err = sosemanuk_keystream(&rc, out_buffer, out_len);
+err = sosemanuk_keystream(&ss, out, outlen);
 \end{verbatim}
 
-When finished you should wipe the key and run contexts:
+When finished you should wipe the key by running \textit{sosemanuk\_done()}.
 \begin{verbatim}
-err = sosemanuk_done(&kc, &rc);
+err = sosemanuk_done(&ss);
 \end{verbatim}
 
-To do multiple encryptions and decryptions with the same key, you can reset the algorithm
-using \textit{sosemanuk\_init()} if you saved the key context and did not wipe it with \textit{sosemanuk\_done()}.
-You will want to use a different iv but you do not need to re-run \textit{sosemanuk\_schedule()} again.
+To do multiple encryptions and decryptions with the same key, you will want to set the iv but
+you do not need to re-run \textit{sosemanuk\_setup()} again, unless of course, you called
+\textit{sosemanuk\_done()}.
 
 \mysection{RC4}
 

src/stream/sosemanuk/sosemanuk.c

@@ -194,11 +194,11 @@
 /* ======================================================================== */
 
 /*
- * Key schedule: initialize the key context structure with the provided
- * secret key. The secret key is an array of 1 to 32 bytes.
+ * Initialize Sosemanuk's state by providing a key. The key is an array of
+ * 1 to 32 bytes.
  * @param ss       The Sosemanuk state
  * @param key      Key
- * @param keylen   Length of key
+ * @param keylen   Length of key in bytes
  * @return CRYPT_OK on success
  */
 int sosemanuk_setup(sosemanuk_state *ss, unsigned char *key, unsigned long keylen)
@@ -331,12 +331,14 @@ int sosemanuk_setup(sosemanuk_state *ss, unsigned char *key, unsigned long keyle
 
 
 /*
- * Cipher initialization: the cipher internal state is initialized, using
- * the provided key context and IV. The IV length is up to 16 bytes. If
- * "ivlen" is 0 (no IV), then the "iv" parameter can be NULL.
+ * Initialization continues by setting the IV. The IV length is up to 16 bytes.
+ * If "ivlen" is 0 (no IV), then the "iv" parameter can be NULL.  If multiple
+ * encryptions/decryptions are to be performed with the same key and
+ * sosemanuk_done() has not been called, only sosemanuk_setiv() need be called
+ * to set the state.
  * @param ss       The Sosemanuk state
  * @param iv       Initialization vector
- * @param ivlen    Length of iv
+ * @param ivlen    Length of iv in bytes
  * @return CRYPT_OK on success
  */
 int sosemanuk_setiv(sosemanuk_state *ss, unsigned char *iv, unsigned long ivlen)
@@ -743,12 +745,12 @@ static LTC_INLINE void _xorbuf(const unsigned char *in1, const unsigned char *in
  * reference distinct buffers (no partial overlap is allowed).
  * @param ss       The Sosemanuk state
  * @param in       Data in
+ * @param inlen    Length of data in bytes
  * @param out      Data out
- * @param datalen  Length of data
  * @return CRYPT_OK on success
  */
 int sosemanuk_crypt(sosemanuk_state *ss,
-                        const unsigned char *in, unsigned long datalen, unsigned char *out)
+                        const unsigned char *in, unsigned long inlen, unsigned char *out)
 {
     LTC_ARGCHK(ss  != NULL);
     LTC_ARGCHK(in  != NULL);
@@ -757,37 +759,38 @@ int sosemanuk_crypt(sosemanuk_state *ss,
     if (ss->ptr < (sizeof(ss->buf))) {
         unsigned long rlen = (sizeof(ss->buf)) - ss->ptr;
 
-        if (rlen > datalen)
-            rlen = datalen;
+        if (rlen > inlen)
+            rlen = inlen;
         _xorbuf(ss->buf + ss->ptr, in, out, rlen);
         in += rlen;
         out += rlen;
-        datalen -= rlen;
+        inlen -= rlen;
         ss->ptr += rlen;
     }
-    while (datalen > 0) {
+    while (inlen > 0) {
         _sosemanuk_internal(ss);
-        if (datalen >= sizeof(ss->buf)) {
+        if (inlen >= sizeof(ss->buf)) {
             _xorbuf(ss->buf, in, out, sizeof(ss->buf));
             in += sizeof(ss->buf);
             out += sizeof(ss->buf);
-            datalen -= sizeof(ss->buf);
+            inlen -= sizeof(ss->buf);
         } else {
-            _xorbuf(ss->buf, in, out, datalen);
-            ss->ptr = datalen;
-            datalen = 0;
+            _xorbuf(ss->buf, in, out, inlen);
+            ss->ptr = inlen;
+            inlen = 0;
         }
     }
     return CRYPT_OK;
 }
 
 
+
 /*
  * Cipher operation, as a PRNG: the provided output buffer is filled with
  * pseudo-random bytes as output from the stream cipher.
  * @param ss       The Sosemanuk state
  * @param out      Data out
- * @param outlen   Length of output
+ * @param outlen   Length of output in bytes
  * @return CRYPT_OK on success
  */
 int sosemanuk_keystream(sosemanuk_state *ss, unsigned char *out, unsigned long outlen)
@@ -801,7 +804,7 @@ int sosemanuk_keystream(sosemanuk_state *ss, unsigned char *out, unsigned long o
 
 /*
  * Terminate and clear Sosemanuk key context
- * @param kc      The Sosemanuk key context
+ * @param ss      The Sosemanuk state
  * @return CRYPT_OK on success
  */
 int sosemanuk_done(sosemanuk_state *ss)