From 844b7cfcb0e3a72bb8dacc247e5cf104f8f0b36e Mon Sep 17 00:00:00 2001
From: Pietro Cerutti <gahr@gahr.ch>
Date: Fri, 18 Nov 2016 16:49:37 +0000
Subject: [PATCH] build: enhance mutt_to_base64() (and callers)

- take chars and cast to unsigned chars inside, remove casts from callers
- return the number of characters written to the output buffers
- Doxygenize and verboize the documentation

Closes: #250
---
 base64.c         | 34 +++++++++++++++++++++++++++++-----
 imap/auth_cram.c |  3 +--
 imap/auth_gss.c  |  8 ++++----
 protos.h         |  2 +-
 4 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/base64.c b/base64.c
index fd3ffb88a..0245a7a6a 100644
--- a/base64.c
+++ b/base64.c
@@ -48,10 +48,24 @@
 
 #define BAD     -1
 
-/* raw bytes to null-terminated base 64 string */
-void mutt_to_base64 (unsigned char *out, const unsigned char *in, size_t len,
-		     size_t olen)
+/**
+ * mutt_to_base64 - convert raw bytes to null-terminated base64 string.
+ *
+ * @param out Output buffer for the base64 encoded string.
+ * @param cin Input buffer for the raw bytes.
+ * @param len Length of the input buffer.
+ * @param olen Length of the output buffer.
+ * @return The length of the string written to the output buffer.
+ *
+ * This function performs base64 encoding. The resulting string is guaranteed
+ * to be null-terminated. The number of characters up to the terminating
+ * null-byte is returned (equivalent to calling strlen() on the output buffer
+ * after this function returns).
+ */
+size_t mutt_to_base64 (char *out, const char *cin, size_t len, size_t olen)
 {
+  unsigned char *begin = (unsigned char *)out;
+  const unsigned char *in = (const unsigned char *)cin;
   while (len >= 3 && olen > 10)
   {
     *out++ = B64Chars[in[0] >> 2];
@@ -77,10 +91,20 @@ void mutt_to_base64 (unsigned char *out, const unsigned char *in, size_t len,
     *out++ = '=';
   }
   *out = '\0';
+  return out - (char *)begin;
 }
 
-/* Convert '\0'-terminated base 64 string to raw bytes.
- * Returns length of returned buffer, or -1 on error */
+/**
+ * mutt_from_base64 - convert null-terminated base64 string to raw bytes.
+ *
+ * @param out Output buffer for the raw bytes.
+ * @param cin Input buffer for the null-terminated base64-encoded string
+ * @return The number of bytes written on success, -1 on error.
+ *
+ * This function performs base64 decoding. The resulting buffer is NOT
+ * null-terminated. If the input buffer contains invalid base64 characters,
+ * this function returns -1.
+ */
 int mutt_from_base64 (char *out, const char *in)
 {
   int len = 0;
diff --git a/imap/auth_cram.c b/imap/auth_cram.c
index 9b6db9af6..f6c8e4e38 100644
--- a/imap/auth_cram.c
+++ b/imap/auth_cram.c
@@ -106,8 +106,7 @@ imap_auth_res_t imap_auth_cram_md5 (IMAP_DATA* idata, const char* method)
    * plus the additional debris
    */
   
-  mutt_to_base64 ((unsigned char*) ibuf, (unsigned char*) obuf, strlen (obuf),
-		  sizeof (ibuf) - 2);
+  mutt_to_base64 (ibuf, obuf, strlen (obuf), sizeof (ibuf) - 2);
   safe_strcat (ibuf, sizeof (ibuf), "\r\n");
   mutt_socket_write (idata->conn, ibuf);
 
diff --git a/imap/auth_gss.c b/imap/auth_gss.c
index 39786c4f1..c4f3b0226 100644
--- a/imap/auth_gss.c
+++ b/imap/auth_gss.c
@@ -160,7 +160,7 @@ imap_auth_res_t imap_auth_gss (IMAP_DATA* idata, const char* method)
 
   /* now start the security context initialisation loop... */
   dprint (2, (debugfile, "Sending credentials\n"));
-  mutt_to_base64 ((unsigned char*) buf1, send_token.value, send_token.length,
+  mutt_to_base64 (buf1, send_token.value, send_token.length,
     sizeof (buf1) - 2);
   gss_release_buffer (&min_stat, &send_token);
   safe_strcat (buf1, sizeof (buf1), "\r\n");
@@ -197,8 +197,8 @@ imap_auth_res_t imap_auth_gss (IMAP_DATA* idata, const char* method)
 
       goto err_abort_cmd;
     }
-    mutt_to_base64 ((unsigned char*) buf1, send_token.value,
-      send_token.length, sizeof (buf1) - 2);
+    mutt_to_base64 (buf1, send_token.value, send_token.length,
+      sizeof (buf1) - 2);
     gss_release_buffer (&min_stat, &send_token);
     safe_strcat (buf1, sizeof (buf1), "\r\n");
     mutt_socket_write (idata->conn, buf1);
@@ -267,7 +267,7 @@ imap_auth_res_t imap_auth_gss (IMAP_DATA* idata, const char* method)
     goto err_abort_cmd;
   }
 
-  mutt_to_base64 ((unsigned char*) buf1, send_token.value, send_token.length,
+  mutt_to_base64 (buf1, send_token.value, send_token.length,
 		  sizeof (buf1) - 2);
   dprint (2, (debugfile, "Requesting authorisation as %s\n",
     idata->conn->account.user));
diff --git a/protos.h b/protos.h
index a0aaf6f64..f9cd30976 100644
--- a/protos.h
+++ b/protos.h
@@ -423,7 +423,7 @@ pid_t mutt_create_filter_fd (const char *, FILE **, FILE **, FILE **, int, int,
 ADDRESS *alias_reverse_lookup (ADDRESS *);
 
 /* base64.c */
-void mutt_to_base64 (unsigned char*, const unsigned char*, size_t, size_t);
+size_t mutt_to_base64 (char*, const char*, size_t, size_t);
 int mutt_from_base64 (char*, const char*);
 
 /* utf8.c */
-- 
2.40.0