Various changes to the des interface

Mostly stylistic changes. Cleaned up documentation.

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

3 files changed, 108 insertions, 82 deletions

diff --git a/src/common/des.c b/src/common/des.c
index 706aafbdd..c680610e9 100644
--- a/src/common/des.c
+++ b/src/common/des.c
@@ -24,26 +24,23 @@
 
 #include "common/cbasetypes.h"
 
+/** @file
+ * Implementation of the des interface.
+ */
+
 struct des_interface des_s;
 struct des_interface *des;
 
-/// DES (Data Encryption Standard) algorithm, modified version.
-/// @see http://www.eathena.ws/board/index.php?autocom=bugtracker&showbug=5099.
-/// @see http://en.wikipedia.org/wiki/Data_Encryption_Standard
-/// @see http://en.wikipedia.org/wiki/DES_supplementary_material
-
-
 /// Bitmask for accessing individual bits of a byte.
 static const uint8_t mask[8] = {
 	0x80, 0x40, 0x20, 0x10, 0x08, 0x04, 0x02, 0x01
 };
 
-
-/// Initial permutation (IP).
-static void IP(struct BIT64 *src)
+/**
+ * Initial permutation (IP).
+ */
+static void des_IP(struct des_bit64 *src)
 {
-	struct BIT64 tmp = {{0}};
-
 	static const uint8_t ip_table[64] = {
 		58, 50, 42, 34, 26, 18, 10,  2,
 		60, 52, 44, 36, 28, 20, 12,  4,
@@ -54,24 +51,23 @@ static void IP(struct BIT64 *src)
 		61, 53, 45, 37, 29, 21, 13,  5,
 		63, 55, 47, 39, 31, 23, 15,  7,
 	};
+	struct des_bit64 tmp = {{0}};
+	int i;
 
-	size_t i;
-	for( i = 0; i < ARRAYLENGTH(ip_table); ++i )
-	{
+	for(i = 0; i < ARRAYLENGTH(ip_table); ++i) {
 		uint8_t j = ip_table[i] - 1;
-		if( src->b[(j >> 3) & 7] &  mask[j & 7] )
-			tmp .b[(i >> 3) & 7] |= mask[i & 7];
+		if (src->b[(j >> 3) & 7] &  mask[j & 7])
+			tmp.b[(i >> 3) & 7] |= mask[i & 7];
 	}
 
 	*src = tmp;
 }
 
-
-/// Final permutation (IP^-1).
-static void FP(struct BIT64 *src)
+/**
+ * Final permutation (IP^-1).
+ */
+static void des_FP(struct des_bit64 *src)
 {
-	struct BIT64 tmp = {{0}};
-
 	static const uint8_t fp_table[64] = {
 		40,  8, 48, 16, 56, 24, 64, 32,
 		39,  7, 47, 15, 55, 23, 63, 31,
@@ -82,24 +78,26 @@ static void FP(struct BIT64 *src)
 		34,  2, 42, 10, 50, 18, 58, 26,
 		33,  1, 41,  9, 49, 17, 57, 25,
 	};
+	struct des_bit64 tmp = {{0}};
+	int i;
 
-	size_t i;
-	for( i = 0; i < ARRAYLENGTH(fp_table); ++i )
-	{
+	for (i = 0; i < ARRAYLENGTH(fp_table); ++i) {
 		uint8_t j = fp_table[i] - 1;
-		if( src->b[(j >> 3) & 7] &  mask[j & 7] )
-			tmp .b[(i >> 3) & 7] |= mask[i & 7];
+		if (src->b[(j >> 3) & 7] &  mask[j & 7])
+			tmp.b[(i >> 3) & 7] |= mask[i & 7];
 	}
 
 	*src = tmp;
 }
 
-
-/// Expansion (E).
-/// Expands upper four 8-bits (32b) into eight 6-bits (48b).
-static void E(struct BIT64 *src)
+/**
+ * Expansion (E).
+ *
+ * Expands upper four 8-bits (32b) into eight 6-bits (48b).
+ */
+static void des_E(struct des_bit64 *src)
 {
-	struct BIT64 tmp = {{0}};
+	struct des_bit64 tmp = {{0}};
 
 #if 0
 	// original
@@ -113,13 +111,12 @@ static void E(struct BIT64 *src)
 		24, 25, 26, 27, 28, 29,
 		28, 29, 30, 31, 32,  1,
 	};
+	int i;
 
-	size_t i;
-	for( i = 0; i < ARRAYLENGTH(expand_table); ++i )
-	{
+	for (i = 0; i < ARRAYLENGTH(expand_table); ++i) {
 		uint8_t j = expand_table[i] - 1;
-		if( src->b[j / 8 + 4] &  mask[j % 8] )
-			tmp .b[i / 6 + 0] |= mask[i % 6];
+		if (src->b[j / 8 + 4] &  mask[j % 8])
+			tmp.b[i / 6 + 0] |= mask[i % 6];
 	}
 #endif
 	// optimized
@@ -135,12 +132,11 @@ static void E(struct BIT64 *src)
 	*src = tmp;
 }
 
-
-/// Transposition (P-BOX).
-static void TP(struct BIT64 *src)
+/**
+ * Transposition (P-BOX).
+ */
+static void des_TP(struct des_bit64 *src)
 {
-	struct BIT64 tmp = {{0}};
-
 	static const uint8_t tp_table[32] = {
 		16,  7, 20, 21,
 		29, 12, 28, 17,
@@ -151,25 +147,27 @@ static void TP(struct BIT64 *src)
 		19, 13, 30,  6,
 		22, 11,  4, 25,
 	};
+	struct des_bit64 tmp = {{0}};
+	int i;
 
-	size_t i;
-	for( i = 0; i < ARRAYLENGTH(tp_table); ++i )
-	{
+	for (i = 0; i < ARRAYLENGTH(tp_table); ++i) {
 		uint8_t j = tp_table[i] - 1;
-		if( src->b[(j >> 3) + 0] &  mask[j & 7] )
-			tmp .b[(i >> 3) + 4] |= mask[i & 7];
+		if (src->b[(j >> 3) + 0] &  mask[j & 7])
+			tmp.b[(i >> 3) + 4] |= mask[i & 7];
 	}
 
 	*src = tmp;
 }
 
 
-/// Substitution boxes (S-boxes).
-/// NOTE: This implementation was optimized to process two nibbles in one step (twice as fast).
-static void SBOX(struct BIT64 *src)
+/**
+ * Substitution boxes (S-boxes).
+ *
+ * This implementation was optimized to process two nibbles in one step (twice
+ * as fast).
+ */
+static void des_SBOX(struct des_bit64 *src)
 {
-	struct BIT64 tmp = {{0}};
-
 	static const uint8_t s_table[4][64] = {
 		  {
 			0xef, 0x03, 0x41, 0xfd, 0xd8, 0x74, 0x1e, 0x47,  0x26, 0xef, 0xfb, 0x22, 0xb3, 0xd8, 0x84, 0x1e,
@@ -193,10 +191,10 @@ static void SBOX(struct BIT64 *src)
 			0xa0, 0x9f, 0xf6, 0x5c, 0x6a, 0x09, 0x8d, 0xf0,  0x0f, 0xe3, 0x53, 0x25, 0x95, 0x36, 0x28, 0xcb,
 		}
 	};
+	struct des_bit64 tmp = {{0}};
+	int i;
 
-	size_t i;
-	for( i = 0; i < ARRAYLENGTH(s_table); ++i )
-	{
+	for (i = 0; i < ARRAYLENGTH(s_table); ++i) {
 		tmp.b[i] = (s_table[i][src->b[i*2+0]] & 0xf0)
 		         | (s_table[i][src->b[i*2+1]] & 0x0f);
 	}
@@ -204,15 +202,17 @@ static void SBOX(struct BIT64 *src)
 	*src = tmp;
 }
 
-
-/// DES round function.
-/// XORs src[0..3] with TP(SBOX(E(src[4..7]))).
-static void RoundFunction(struct BIT64 *src)
+/**
+ * DES round function.
+ *
+ * XORs src[0..3] with TP(SBOX(E(src[4..7]))).
+ */
+static void des_RoundFunction(struct des_bit64 *src)
 {
-	struct BIT64 tmp = *src;
-	E(&tmp);
-	SBOX(&tmp);
-	TP(&tmp);
+	struct des_bit64 tmp = *src;
+	des_E(&tmp);
+	des_SBOX(&tmp);
+	des_TP(&tmp);
 
 	src->b[0] ^= tmp.b[4];
 	src->b[1] ^= tmp.b[5];
@@ -220,24 +220,27 @@ static void RoundFunction(struct BIT64 *src)
 	src->b[3] ^= tmp.b[7];
 }
 
-
-void des_decrypt_block(struct BIT64 *block)
+/// @copydoc des_interface::decrypt_block()
+void des_decrypt_block(struct des_bit64 *block)
 {
-	IP(block);
-	RoundFunction(block);
-	FP(block);
+	des_IP(block);
+	des_RoundFunction(block);
+	des_FP(block);
 }
 
-
-void des_decrypt(unsigned char* data, size_t size)
+/// @copydoc des_interface::decrypt()
+void des_decrypt(unsigned char *data, size_t size)
 {
-	struct BIT64 *p = (struct BIT64 *)data;
+	struct des_bit64 *p = (struct des_bit64 *)data;
 	size_t i;
 
-	for( i = 0; i*8 < size; i += 8 )
+	for (i = 0; i*8 < size; i += 8)
 		des->decrypt_block(p);
 }
 
+/**
+ * Interface base initialization.
+ */
 void des_defaults(void)
 {
 	des = &des_s;
diff --git a/src/common/des.h b/src/common/des.h
index 61cf2c04a..9924a044b 100644
--- a/src/common/des.h
+++ b/src/common/des.h
@@ -23,17 +23,40 @@
 
 #include "common/hercules.h"
 
+/**
+ * @file
+ *
+ * DES (Data Encryption Standard) algorithm, modified version.
+ *
+ * @see http://www.eathena.ws/board/index.php?autocom=bugtracker&showbug=5099
+ * @see http://en.wikipedia.org/wiki/Data_Encryption_Standard
+ * @see http://en.wikipedia.org/wiki/DES_supplementary_material
+ */
+
 /* Struct definitions */
 
 /// One 64-bit block.
-struct BIT64 {
+struct des_bit64 {
 	uint8_t b[8];
 };
 
 /* Interface */
 
+/// The des interface.
 struct des_interface {
-	void (*decrypt_block) (struct BIT64 *block);
+	/**
+	 * Decrypts a block.
+	 *
+	 * @param[in,out] block The block to decrypt (in-place).
+	 */
+	void (*decrypt_block) (struct des_bit64 *block);
+
+	/**
+	 * Decrypts a buffer.
+	 *
+	 * @param [in,out] data The buffer to decrypt (in-place).
+	 * @param [in]     size The size of the data.
+	 */
 	void (*decrypt) (unsigned char *data, size_t size);
 };
 
@@ -41,6 +64,6 @@ struct des_interface {
 void des_defaults(void);
 #endif // HERCULES_CORE
 
-HPShared struct des_interface *des;
+HPShared struct des_interface *des; ///< Pointer to the des interface implementation.
 
 #endif // COMMON_DES_H
diff --git a/src/common/grfio.c b/src/common/grfio.c
index c5c38455d..7f860acc6 100644
--- a/src/common/grfio.c
+++ b/src/common/grfio.c
@@ -121,9 +121,9 @@ static uint8_t grf_substitution(uint8_t in)
 }
 
 #if 0 /* this is not used anywhere, is it ok to delete?  */
-static void grf_shuffle_enc(struct BIT64 *src)
+static void grf_shuffle_enc(struct des_bit64 *src)
 {
-	struct BIT64 out;
+	struct des_bit64 out;
 
 	out.b[0] = src->b[3];
 	out.b[1] = src->b[4];
@@ -138,9 +138,9 @@ static void grf_shuffle_enc(struct BIT64 *src)
 }
 #endif // 0
 
-static void grf_shuffle_dec(struct BIT64 *src)
+static void grf_shuffle_dec(struct des_bit64 *src)
 {
-	struct BIT64 out;
+	struct des_bit64 out;
 
 	out.b[0] = src->b[3];
 	out.b[1] = src->b[4];
@@ -156,8 +156,8 @@ static void grf_shuffle_dec(struct BIT64 *src)
 
 static void grf_decode_header(unsigned char* buf, size_t len)
 {
-	struct BIT64 *p = (struct BIT64 *)buf;
-	size_t nblocks = len / sizeof(struct BIT64);
+	struct des_bit64 *p = (struct des_bit64 *)buf;
+	size_t nblocks = len / sizeof(struct des_bit64);
 	size_t i;
 
 	// first 20 blocks are all des-encrypted
@@ -169,8 +169,8 @@ static void grf_decode_header(unsigned char* buf, size_t len)
 
 static void grf_decode_full(unsigned char* buf, size_t len, int cycle)
 {
-	struct BIT64 *p = (struct BIT64 *)buf;
-	size_t nblocks = len / sizeof(struct BIT64);
+	struct des_bit64 *p = (struct des_bit64 *)buf;
+	size_t nblocks = len / sizeof(struct des_bit64);
 	int dcycle, scycle;
 	size_t i, j;