Various changes to the md5 interface

Mostly stylistic changes. Cleaned up documentation.

Signed-off-by: Haru <haru@dotalux.com>

2 files changed, 104 insertions, 69 deletions

diff --git a/src/common/md5calc.c b/src/common/md5calc.c
index ad0f7c2d8..bd6b48f10 100644
--- a/src/common/md5calc.c
+++ b/src/common/md5calc.c
@@ -20,30 +20,27 @@
  */
 #define HERCULES_CORE
 
-/***********************************************************
- * md5 calculation algorithm
- *
- * The source code referred to the following URL.
- * http://www.geocities.co.jp/SiliconValley-Oakland/8878/lab17/lab17.html
- *
- ***********************************************************/
-
 #include "md5calc.h"
 
 #include "common/cbasetypes.h"
+#include "common/nullpo.h"
 #include "common/random.h"
 
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
+/** @file
+ * Implementation of the md5 interface.
+ */
+
 struct md5_interface md5_s;
 struct md5_interface *md5;
 
-// Global variable
+/// Global variable
 static unsigned int *pX;
 
-// String Table
+/// String Table
 static const unsigned int T[] = {
 	0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, //0
 	0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501, //4
@@ -63,99 +60,102 @@ static const unsigned int T[] = {
 	0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391  //60
 };
 
-// ROTATE_LEFT   The left is made to rotate x [ n-bit ]. This is diverted as it is from RFC.
+/// The left is made to rotate x [ n-bit ]. This is diverted as it is from RFC.
 #define ROTATE_LEFT(x, n) (((x) << (n)) | ((x) >> (32-(n))))
 
 // The function used for other calculation
-static unsigned int F(unsigned int X, unsigned int Y, unsigned int Z)
+static unsigned int md5_F(unsigned int X, unsigned int Y, unsigned int Z)
 {
 	return (X & Y) | (~X & Z);
 }
-static unsigned int G(unsigned int X, unsigned int Y, unsigned int Z)
+
+static unsigned int md5_G(unsigned int X, unsigned int Y, unsigned int Z)
 {
 	return (X & Z) | (Y & ~Z);
 }
-static unsigned int H(unsigned int X, unsigned int Y, unsigned int Z)
+
+static unsigned int md5_H(unsigned int X, unsigned int Y, unsigned int Z)
 {
 	return X ^ Y ^ Z;
 }
-static unsigned int I(unsigned int X, unsigned int Y, unsigned int Z)
+
+static unsigned int md5_I(unsigned int X, unsigned int Y, unsigned int Z)
 {
 	return Y ^ (X | ~Z);
 }
 
-static unsigned int Round(unsigned int a, unsigned int b, unsigned int FGHI,
+static unsigned int md5_Round(unsigned int a, unsigned int b, unsigned int FGHI,
 		unsigned int k, unsigned int s, unsigned int i)
 {
 	return b + ROTATE_LEFT(a + FGHI + pX[k] + T[i], s);
 }
 
-static void Round1(unsigned int *a, unsigned int b, unsigned int c,
+static void md5_Round1(unsigned int *a, unsigned int b, unsigned int c,
 		unsigned int d,unsigned int k, unsigned int s, unsigned int i)
 {
-	*a = Round(*a, b, F(b,c,d), k, s, i);
+	*a = md5_Round(*a, b, md5_F(b,c,d), k, s, i);
 }
-static void Round2(unsigned int *a, unsigned int b, unsigned int c,
+static void md5_Round2(unsigned int *a, unsigned int b, unsigned int c,
 		unsigned int d,unsigned int k, unsigned int s, unsigned int i)
 {
-	*a = Round(*a, b, G(b,c,d), k, s, i);
+	*a = md5_Round(*a, b, md5_G(b,c,d), k, s, i);
 }
-static void Round3(unsigned int *a, unsigned int b, unsigned int c,
+static void md5_Round3(unsigned int *a, unsigned int b, unsigned int c,
 		unsigned int d,unsigned int k, unsigned int s, unsigned int i)
 {
-	*a = Round(*a, b, H(b,c,d), k, s, i);
+	*a = md5_Round(*a, b, md5_H(b,c,d), k, s, i);
 }
-static void Round4(unsigned int *a, unsigned int b, unsigned int c,
+static void md5_Round4(unsigned int *a, unsigned int b, unsigned int c,
 		unsigned int d,unsigned int k, unsigned int s, unsigned int i)
 {
-	*a = Round(*a, b, I(b,c,d), k, s, i);
+	*a = md5_Round(*a, b, md5_I(b,c,d), k, s, i);
 }
 
-static void MD5_Round_Calculate(const unsigned char *block,
+static void md5_Round_Calculate(const unsigned char *block,
 	unsigned int *A2, unsigned int *B2, unsigned int *C2, unsigned int *D2)
 {
 	//create X It is since it is required.
 	unsigned int X[16]; //512bit 64byte
-	int j,k;
+	int j, k;
 
 	//Save A as AA, B as BB, C as CC, and and D as DD (saving of A, B, C, and D)
-	unsigned int A=*A2, B=*B2, C=*C2, D=*D2;
-	unsigned int AA = A,BB = B,CC = C,DD = D;
+	unsigned int A = *A2, B = *B2, C = *C2, D = *D2;
+	unsigned int AA = A, BB = B, CC = C, DD = D;
 
 	//It is a large region variable reluctantly because of calculation of a round. . . for Round1...4
 	pX = X;
 
 	//Copy block(padding_message) i into X
-	for (j=0,k=0; j<64; j+=4,k++)
-		X[k] = ( (unsigned int )block[j] )         // 8byte*4 -> 32byte conversion
-			| ( ((unsigned int )block[j+1]) << 8 ) // A function called Decode as used in the field of RFC
-			| ( ((unsigned int )block[j+2]) << 16 )
-			| ( ((unsigned int )block[j+3]) << 24 );
-
+	for (j = 0, k = 0; j < 64; j += 4, k++) {
+		X[k] = ((unsigned int)block[j])         // 8byte*4 -> 32byte conversion
+		    | (((unsigned int)block[j+1]) << 8) // A function called Decode as used in the field of RFC
+		    | (((unsigned int)block[j+2]) << 16)
+		    | (((unsigned int)block[j+3]) << 24);
+	}
 
 	//Round 1
-	Round1(&A,B,C,D,  0, 7,  0); Round1(&D,A,B,C,  1, 12,  1); Round1(&C,D,A,B,  2, 17,  2); Round1(&B,C,D,A,  3, 22,  3);
-	Round1(&A,B,C,D,  4, 7,  4); Round1(&D,A,B,C,  5, 12,  5); Round1(&C,D,A,B,  6, 17,  6); Round1(&B,C,D,A,  7, 22,  7);
-	Round1(&A,B,C,D,  8, 7,  8); Round1(&D,A,B,C,  9, 12,  9); Round1(&C,D,A,B, 10, 17, 10); Round1(&B,C,D,A, 11, 22, 11);
-	Round1(&A,B,C,D, 12, 7, 12); Round1(&D,A,B,C, 13, 12, 13); Round1(&C,D,A,B, 14, 17, 14); Round1(&B,C,D,A, 15, 22, 15);
+	md5_Round1(&A,B,C,D,  0, 7,  0); md5_Round1(&D,A,B,C,  1, 12,  1); md5_Round1(&C,D,A,B,  2, 17,  2); md5_Round1(&B,C,D,A,  3, 22,  3);
+	md5_Round1(&A,B,C,D,  4, 7,  4); md5_Round1(&D,A,B,C,  5, 12,  5); md5_Round1(&C,D,A,B,  6, 17,  6); md5_Round1(&B,C,D,A,  7, 22,  7);
+	md5_Round1(&A,B,C,D,  8, 7,  8); md5_Round1(&D,A,B,C,  9, 12,  9); md5_Round1(&C,D,A,B, 10, 17, 10); md5_Round1(&B,C,D,A, 11, 22, 11);
+	md5_Round1(&A,B,C,D, 12, 7, 12); md5_Round1(&D,A,B,C, 13, 12, 13); md5_Round1(&C,D,A,B, 14, 17, 14); md5_Round1(&B,C,D,A, 15, 22, 15);
 
 	//Round 2
-	Round2(&A,B,C,D,  1, 5, 16); Round2(&D,A,B,C,  6, 9, 17); Round2(&C,D,A,B, 11, 14, 18); Round2(&B,C,D,A,  0, 20, 19);
-	Round2(&A,B,C,D,  5, 5, 20); Round2(&D,A,B,C, 10, 9, 21); Round2(&C,D,A,B, 15, 14, 22); Round2(&B,C,D,A,  4, 20, 23);
-	Round2(&A,B,C,D,  9, 5, 24); Round2(&D,A,B,C, 14, 9, 25); Round2(&C,D,A,B,  3, 14, 26); Round2(&B,C,D,A,  8, 20, 27);
-	Round2(&A,B,C,D, 13, 5, 28); Round2(&D,A,B,C,  2, 9, 29); Round2(&C,D,A,B,  7, 14, 30); Round2(&B,C,D,A, 12, 20, 31);
+	md5_Round2(&A,B,C,D,  1, 5, 16); md5_Round2(&D,A,B,C,  6, 9, 17); md5_Round2(&C,D,A,B, 11, 14, 18); md5_Round2(&B,C,D,A,  0, 20, 19);
+	md5_Round2(&A,B,C,D,  5, 5, 20); md5_Round2(&D,A,B,C, 10, 9, 21); md5_Round2(&C,D,A,B, 15, 14, 22); md5_Round2(&B,C,D,A,  4, 20, 23);
+	md5_Round2(&A,B,C,D,  9, 5, 24); md5_Round2(&D,A,B,C, 14, 9, 25); md5_Round2(&C,D,A,B,  3, 14, 26); md5_Round2(&B,C,D,A,  8, 20, 27);
+	md5_Round2(&A,B,C,D, 13, 5, 28); md5_Round2(&D,A,B,C,  2, 9, 29); md5_Round2(&C,D,A,B,  7, 14, 30); md5_Round2(&B,C,D,A, 12, 20, 31);
 
 	//Round 3
-	Round3(&A,B,C,D,  5, 4, 32); Round3(&D,A,B,C,  8, 11, 33); Round3(&C,D,A,B, 11, 16, 34); Round3(&B,C,D,A, 14, 23, 35);
-	Round3(&A,B,C,D,  1, 4, 36); Round3(&D,A,B,C,  4, 11, 37); Round3(&C,D,A,B,  7, 16, 38); Round3(&B,C,D,A, 10, 23, 39);
-	Round3(&A,B,C,D, 13, 4, 40); Round3(&D,A,B,C,  0, 11, 41); Round3(&C,D,A,B,  3, 16, 42); Round3(&B,C,D,A,  6, 23, 43);
-	Round3(&A,B,C,D,  9, 4, 44); Round3(&D,A,B,C, 12, 11, 45); Round3(&C,D,A,B, 15, 16, 46); Round3(&B,C,D,A,  2, 23, 47);
+	md5_Round3(&A,B,C,D,  5, 4, 32); md5_Round3(&D,A,B,C,  8, 11, 33); md5_Round3(&C,D,A,B, 11, 16, 34); md5_Round3(&B,C,D,A, 14, 23, 35);
+	md5_Round3(&A,B,C,D,  1, 4, 36); md5_Round3(&D,A,B,C,  4, 11, 37); md5_Round3(&C,D,A,B,  7, 16, 38); md5_Round3(&B,C,D,A, 10, 23, 39);
+	md5_Round3(&A,B,C,D, 13, 4, 40); md5_Round3(&D,A,B,C,  0, 11, 41); md5_Round3(&C,D,A,B,  3, 16, 42); md5_Round3(&B,C,D,A,  6, 23, 43);
+	md5_Round3(&A,B,C,D,  9, 4, 44); md5_Round3(&D,A,B,C, 12, 11, 45); md5_Round3(&C,D,A,B, 15, 16, 46); md5_Round3(&B,C,D,A,  2, 23, 47);
 
 	//Round 4
-	Round4(&A,B,C,D,  0, 6, 48); Round4(&D,A,B,C,  7, 10, 49); Round4(&C,D,A,B, 14, 15, 50); Round4(&B,C,D,A,  5, 21, 51);
-	Round4(&A,B,C,D, 12, 6, 52); Round4(&D,A,B,C,  3, 10, 53); Round4(&C,D,A,B, 10, 15, 54); Round4(&B,C,D,A,  1, 21, 55);
-	Round4(&A,B,C,D,  8, 6, 56); Round4(&D,A,B,C, 15, 10, 57); Round4(&C,D,A,B,  6, 15, 58); Round4(&B,C,D,A, 13, 21, 59);
-	Round4(&A,B,C,D,  4, 6, 60); Round4(&D,A,B,C, 11, 10, 61); Round4(&C,D,A,B,  2, 15, 62); Round4(&B,C,D,A,  9, 21, 63);
+	md5_Round4(&A,B,C,D,  0, 6, 48); md5_Round4(&D,A,B,C,  7, 10, 49); md5_Round4(&C,D,A,B, 14, 15, 50); md5_Round4(&B,C,D,A,  5, 21, 51);
+	md5_Round4(&A,B,C,D, 12, 6, 52); md5_Round4(&D,A,B,C,  3, 10, 53); md5_Round4(&C,D,A,B, 10, 15, 54); md5_Round4(&B,C,D,A,  1, 21, 55);
+	md5_Round4(&A,B,C,D,  8, 6, 56); md5_Round4(&D,A,B,C, 15, 10, 57); md5_Round4(&C,D,A,B,  6, 15, 58); md5_Round4(&B,C,D,A, 13, 21, 59);
+	md5_Round4(&A,B,C,D,  4, 6, 60); md5_Round4(&D,A,B,C, 11, 10, 61); md5_Round4(&C,D,A,B,  2, 15, 62); md5_Round4(&B,C,D,A,  9, 21, 63);
 
 	// Then perform the following additions. (let's add)
 	*A2 = A + AA;
@@ -167,7 +167,8 @@ static void MD5_Round_Calculate(const unsigned char *block,
 	memset(pX, 0, sizeof(X));
 }
 
-static void MD5_String2binary(const char * string, unsigned char * output)
+/// @copydoc md5_interface::binary()
+static void md5_string2binary(const char *string, unsigned char *output)
 {
 //var
 	/*8bit*/
@@ -199,7 +200,7 @@ static void MD5_String2binary(const char * string, unsigned char * output)
 
 	//1-2  Repeat calculation until length becomes less than 64 bytes.
 	for (i=string_byte_len; 64<=i; i-=64,pstring+=64)
-		MD5_Round_Calculate(pstring, A,B,C,D);
+		md5_Round_Calculate(pstring, A,B,C,D);
 
 	//1-3
 	copy_len = string_byte_len % 64;                               //The number of bytes which remained is computed.
@@ -210,7 +211,7 @@ static void MD5_String2binary(const char * string, unsigned char * output)
 	//1-4
 	//If 56 bytes or more (less than 64 bytes) of remainder becomes, it will calculate by extending to 64 bytes.
 	if (56 <= copy_len) {
-		MD5_Round_Calculate(padding_message, A,B,C,D);
+		md5_Round_Calculate(padding_message, A,B,C,D);
 		memset(padding_message, 0, 56); //56 bytes is newly fill uped with 0.
 	}
 
@@ -222,24 +223,25 @@ static void MD5_String2binary(const char * string, unsigned char * output)
 	if (UINT_MAX / 8 < string_byte_len) {
 		unsigned int high = (string_byte_len - UINT_MAX / 8) * 8;
 		memcpy(&padding_message[60], &high, 4);
-	} else
+	} else {
 		memset(&padding_message[60], 0, 4); //In this case, it is good for a higher rank at 0.
+	}
 
 	//Step 4.Process Message in 16-Word Blocks (calculation of MD5)
-	MD5_Round_Calculate(padding_message, A,B,C,D);
+	md5_Round_Calculate(padding_message, A,B,C,D);
 
 	//Step 5.Output (output)
 	memcpy(output,msg_digest,16);
 }
 
-//-------------------------------------------------------------------
-// The function for the exteriors
-
-/** output is the coded character sequence in the character sequence which wants to code string. */
-void MD5_String(const char *string, char *output)
+/// @copydoc md5_interface::string()
+void md5_string(const char *string, char *output)
 {
 	unsigned char digest[16];
 
+	nullpo_retv(string);
+	nullpo_retv(output);
+
 	md5->binary(string,digest);
 	snprintf(output, 33, "%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x",
 		digest[ 0], digest[ 1], digest[ 2], digest[ 3],
@@ -248,19 +250,24 @@ void MD5_String(const char *string, char *output)
 		digest[12], digest[13], digest[14], digest[15]);
 }
 
-/** output is a sequence of non-zero characters to be used as password salt. */
-void MD5_Salt(unsigned int len, char * output)
+/// @copydoc md5_interface::salt();
+void md5_salt(int len, char *output)
 {
-	unsigned int i;
-	for( i = 0; i < len; ++i )
+	int i;
+	Assert_retv(len > 0);
+
+	for (i = 0; i < len; ++i)
 		output[i] = (char)(1 + rnd() % 255);
 
 }
 
+/**
+ * Interface base initialization.
+ */
 void md5_defaults(void)
 {
 	md5 = &md5_s;
-	md5->binary = MD5_String2binary;
-	md5->string = MD5_String;
-	md5->salt = MD5_Salt;
+	md5->binary = md5_string2binary;
+	md5->string = md5_string;
+	md5->salt = md5_salt;
 }
diff --git a/src/common/md5calc.h b/src/common/md5calc.h
index 1611b6fee..b4d4995f9 100644
--- a/src/common/md5calc.h
+++ b/src/common/md5calc.h
@@ -23,16 +23,44 @@
 
 #include "common/hercules.h"
 
+/** @file
+ * md5 calculation algorithm.
+ *
+ * The source code referred to the following URL.
+ * http://www.geocities.co.jp/SiliconValley-Oakland/8878/lab17/lab17.html
+ */
+
+/// The md5 interface
 struct md5_interface {
+	/**
+	 * Hashes a string, returning the hash in string format.
+	 *
+	 * @param[in]  string The source string (NUL terminated).
+	 * @param[out] output Output buffer (at least 33 bytes available).
+	 */
 	void (*string) (const char *string, char *output);
+
+	/**
+	 * Hashes a string, returning the buffer in binary format.
+	 *
+	 * @param[in]  string The source string.
+	 * @param[out] output Output buffer (at least 16 bytes available).
+	 */
 	void (*binary) (const char *string, unsigned char *output);
-	void (*salt) (unsigned int len, char *output);
+
+	/**
+	 * Generates a random salt.
+	 *
+	 * @param[in]  len    The desired salt length.
+	 * @param[out] output The output buffer (at least len bytes available).
+	 */
+	void (*salt) (int len, char *output);
 };
 
 #ifdef HERCULES_CORE
 void md5_defaults(void);
 #endif // HERCULES_CORE
 
-HPShared struct md5_interface *md5;
+HPShared struct md5_interface *md5; ///< Pointer to the md5 interface.
 
 #endif /* COMMON_MD5CALC_H */