doc: fixed documentation for crypto headers

sys/include/crypto/aes.h

@@ -51,10 +51,15 @@ typedef uint8_t u8;
 #define AES_BLOCK_SIZE    16
 #define AES_KEY_SIZE      16
 
-
+/**
+ * @brief AES key
+ * @see cipher_context_t
+ */
 struct aes_key_st {
+    /** @cond INTERNAL */
     uint32_t rd_key[4 * (AES_MAXNR + 1)];
     int rounds;
+    /** @endcond */
 };
 
 typedef struct aes_key_st AES_KEY;
@@ -63,6 +68,7 @@ typedef struct aes_key_st AES_KEY;
  * @brief the cipher_context_t-struct adapted for AES
  */
 typedef struct {
+    /** context data buffer */
     uint32_t context[(4 * (AES_MAXNR + 1)) + 1];
 } aes_context_t;
 

sys/include/crypto/cbcmode.h

@@ -77,22 +77,22 @@ enum {
  * @param   spill1  test1
  */
 typedef struct CBCModeContext {
-        // Spill-Block 1 for temporary usage
+    /** Spill-Block 1 for temporary usage */
     uint8_t spill1 [CBCMODE_MAX_BLOCK_SIZE ];
-    // Spill-Block 2 for temporary usage
+    /** Spill-Block 2 for temporary usage */
     uint8_t spill2 [CBCMODE_MAX_BLOCK_SIZE ];
-    // the blocksize currently used
+    /** the blocksize currently used */
     uint8_t bsize;
-    // how many more bytes of ciphertext do we need to recv
+    /** how many more bytes of ciphertext do we need to recv */
     uint16_t remaining;
-    // how many bytes of plaintext we've deciphered.
+    /** how many bytes of plaintext we've deciphered. */
     uint16_t completed;
-    // TRUE iff spill1 is the accumulator and spill2 holds prev cipher text.
-    // false o.w.
+    /** TRUE iff spill1 is the accumulator and spill2 holds prev cipher text. */
+    /** false o.w. */
     uint8_t accum;
-    // into the accumulator
+    /** into the accumulator */
     uint8_t offset;
-    // state enum
+    /** state enum */
     uint8_t state;
 } /*__attribute__ ((packed)) */ CBCModeContext;
 
@@ -166,6 +166,7 @@ void dump_buffer(char *bufName, uint8_t *buf, uint8_t size);
  *          cipher buffer are the same. (they may either be the same or
  *          non-overlapping. partial overlaps are not supported).
  *
+ * @param   context       context object for this encryption
  * @param   plain_blocks  a plaintext block numBlocks, where each block is of
  *                        blockSize bytes
  * @param   cipher_blocks an array of numBlocks * blockSize bytes to hold the
@@ -190,6 +191,7 @@ int block_cipher_mode_encrypt(CipherModeContext *context, uint8_t *plain_blocks,
  *          cipher buffer are the same. (they may either be the same or
  *          non-overlapping. partial overlaps are not supported).
  *
+ * @param   context        context object for this decryption
  * @param   cipher_blocks  an array of num_bytes * blockSize bytes that holds
  *                         the cipher text
  * @param   plain_blocks   an array of num_bytes * blockSize bytes to hold the

sys/include/crypto/ciphers.h

@@ -39,7 +39,7 @@ extern "C" {
 // #define TWOFISH
 // #define SKIPJACK
 
-/// the length of keys in bytes
+/** @brief the length of keys in bytes */
 #define PARSEC_MAX_BLOCK_CIPHERS  5
 #define CIPHERS_KEYSIZE           20
 
@@ -55,15 +55,15 @@ extern "C" {
  */
 typedef struct {
 #if defined(RC5)
-    uint8_t context[104];             // supports RC5 and lower
+    uint8_t context[104];             /**< supports RC5 and lower */
 #elif defined(THREEDES)
-    uint8_t context[24];              // supports ThreeDES and lower
+    uint8_t context[24];              /**< supports ThreeDES and lower */
 #elif defined(AES)
-    uint8_t context[CIPHERS_KEYSIZE]; // supports AES and lower
+    uint8_t context[CIPHERS_KEYSIZE]; /**< supports AES and lower */
 #elif defined(TWOFISH)
-    uint8_t context[CIPHERS_KEYSIZE]; // supports TwoFish and lower
+    uint8_t context[CIPHERS_KEYSIZE]; /**< supports TwoFish and lower */
 #elif defined(SKIPJACK)
-    uint8_t context[20];              // supports SkipJack and lower
+    uint8_t context[20];              /**< supports SkipJack and lower */
 #endif
 } cipher_context_t;
 
@@ -72,53 +72,43 @@ typedef struct {
  * @brief   BlockCipher-Interface for the Cipher-Algorithms
  */
 typedef struct {
+    /** the name of the cipher algorithm as a string */
     char name[10];
-    // the init function
+    /** the init function */
     int (*BlockCipher_init)(cipher_context_t *context, uint8_t blockSize,
                             uint8_t keySize, uint8_t *key);
-    // the encrypt function
+    /** the encrypt function */
     int (*BlockCipher_encrypt)(cipher_context_t *context, uint8_t *plainBlock,
                                uint8_t *cipherBlock);
-    // the decrypt function
+    /** the decrypt function */
     int (*BlockCipher_decrypt)(cipher_context_t *context, uint8_t *cipherBlock,
                                uint8_t *plainBlock);
-    // the setupKey function
+    /** the setupKey function */
     int (*setupKey)(cipher_context_t *context, uint8_t *key, uint8_t keysize);
-    // read the BlockSize of this Cipher
+    /** read the BlockSize of this Cipher */
     uint8_t (*BlockCipherInfo_getPreferredBlockSize)(void);
 } block_cipher_interface_t;
 
 
+/**
+ * @brief The cipher mode context
+ */
 typedef struct CipherModeContext {
-    cipher_context_t cc;            // CipherContext for the cipher-operations
-    uint8_t context[24];         // context for the block-cipher-modes'
-                                 // internal functions
-    //CBCModeContext* context;
+    cipher_context_t cc;         /**< CipherContext for the cipher-operations */
+    uint8_t context[24];         /**< context for the block-cipher-modes' */
 } CipherModeContext;
 
 
 /**
- * @brief       struct for an archive of all available ciphers
+ * @brief  struct for an archive of all available ciphers
  */
 typedef struct {
-        // the number of available ciphers
+    /** the number of available ciphers */
     uint8_t NoCiphers;
-    // the ciphers in form or BlockCipherInterface_ts
+    /** the ciphers in form or BlockCipherInterface_ts */
     block_cipher_interface_t ciphers[PARSEC_MAX_BLOCK_CIPHERS];
 } block_cipher_archive_t;
 
-typedef struct {
-        // cipher_context_t for the cipher-operations
-    cipher_context_t cc;
-#if defined(AES) || defined (TWOFISH)
-    // supports 16-Byte blocksize
-    uint8_t context[20];
-#else
-    // supports 8-Byte blocksize
-    uint8_t context[12];
-#endif
-} cipher_mac_context_t;
-
 #ifdef __cplusplus
 }
 #endif

sys/include/crypto/rc5.h

@@ -60,7 +60,9 @@ extern "C" {
  * @brief the cipher_context_t adapted for RC5
  */
 typedef struct {
+    /** @cond INTERNAL */
     uint32_t skey [2 * (RC5_ROUNDS + 1)];
+    /** @endcond */
 } rc5_context_t;
 
 /**

sys/include/crypto/sha256.h

@@ -57,9 +57,15 @@ extern "C" {
 
 #define SHA256_DIGEST_LENGTH 32
 
+/**
+ * @brief Context for ciper operatins based on sha256
+ */
 typedef struct {
+    /** global state */
     uint32_t state[8];
+    /** processed bytes counter */
     uint32_t count[2];
+    /** data buffer */
     unsigned char buf[64];
 } sha256_context_t;
 

sys/include/crypto/skipjack.h

@@ -91,7 +91,7 @@ extern "C" {
  * @brief The cipher_context_t adapted for SkipJack
  */
 typedef struct {
-        // 2 times keysize. makes unrolling keystream easier / efficient
+    /** 2 times keysize. makes unrolling keystream easier / efficient */
     uint8_t skey [ 20 ];
 } skipjack_context_t;
 

sys/include/crypto/twofish.h

@@ -198,15 +198,15 @@ extern "C" {
 /**
  * @brief  Structure for an expanded Twofish key.
  *
- * @param   s   contains the key-dependent S-boxes composed with the MDS
- *              matrix;
- * @param   w   contains the eight "whitening" subkeys, K[0] through K[7].
- * @param   k   holds the remaining, "round" subkeys.
- *
  * Note that k[i] corresponds to what the Twofish paper calls K[i+8].
  */
 typedef struct {
-    uint32_t s[4][256], w[8], k[32];
+ /** contains the key-dependent S-boxes composed with the MDS matrix */
+    uint32_t s[4][256],
+ /** contains the eight "whitening" subkeys, K[0] through K[7] */
+    w[8],
+ /** holds the remaining, "round" subkeys */
+    k[32];
 } twofish_context_t;