crypto: Improve and fix comments

Update return values in documentation
Improve comments with separate @return statement for each rv
Remove incorrect return value for aes_init
Use @return instead of @returns
Fix comment lines over 80 chars

sys/include/crypto/aes.h

@@ -41,7 +41,7 @@ typedef uint8_t u8;
 /* This controls loop-unrolling in aes_core.c */
 #undef FULL_UNROLL
 # define GETU32(pt) (((u32)(pt)[0] << 24) ^ ((u32)(pt)[1] << 16) ^ \
-                             ((u32)(pt)[2] <<  8) ^ ((u32)(pt)[3]))
+                     ((u32)(pt)[2] <<  8) ^ ((u32)(pt)[3]))
 # define PUTU32(ct, st) { (ct)[0] = (u8)((st) >> 24); \
                               (ct)[1] = (u8)((st) >> 16); \
                               (ct)[2] = (u8)((st) >>  8); \
@@ -75,14 +75,15 @@ typedef struct {
 /**
  * @brief   initializes the AES Cipher-algorithm with the passed parameters
  *
- * @param       context   the cipher_context_t-struct to save the initialization
+ * @param       context   the cipher_context_t-struct to save the
- *                        of the cipher in
+ *                        initialization of the cipher in
  * @param       keySize   the size of the key
  * @param       key       a pointer to the key
  *
  * @return  CIPHER_INIT_SUCCESS if the initialization was successful.
- *          The command may be unsuccessful if the key size is not valid.
+ * @return  CIPHER_ERR_BAD_CONTEXT_SIZE if CIPHER_MAX_CONTEXT_SIZE has not
- *          CIPHER_ERR_BAD_CONTEXT_SIZE if CIPHER_MAX_CONTEXT_SIZE has not been defined (which means that the cipher has not been included in the build)
+ *          been defined (which means that the cipher has not been included
+ *          in the build)
  */
 int aes_init(cipher_context_t *context, const uint8_t *key, uint8_t keySize);
 
@@ -99,7 +100,9 @@ int aes_init(cipher_context_t *context, const uint8_t *key, uint8_t keySize);
  * @param       cipher_block  a pointer to the place where the ciphertext will
  *                            be stored
  *
- * @return  1 or result of aes_set_encrypt_key if it failed
+ * @return  1 on success
+ * @return  A negative value if the cipher key cannot be expanded with the
+ *          AES key schedule
  */
 int aes_encrypt(const cipher_context_t *context, const uint8_t *plain_block,
                 uint8_t *cipher_block);
@@ -117,8 +120,9 @@ int aes_encrypt(const cipher_context_t *context, const uint8_t *plain_block,
  * @param       plain_block   a pointer to the place where the decrypted
  *                            plaintext will be stored
  *
- * @return  1 or negative value if cipher key cannot be expanded into
+ * @return  1 on success
- *          decryption key schedule
+ * @return  A negative value if the cipher key cannot be expanded with the
+ *          AES key schedule
  */
 int aes_decrypt(const cipher_context_t *context, const uint8_t *cipher_block,
                 uint8_t *plain_block);

sys/include/crypto/chacha.h

@@ -60,8 +60,8 @@ typedef struct
  * @param[in]  keylen  Length (in bytes) of @p key. Must be 16 or 32.
  * @param[in]  nonce   IV / nonce to use.
  *
- * @returns `== 0` on success.
+ * @return     `== 0` on success.
- * @returns `< 0` if an illegal value for @p rounds or @p keylen was suppplied.
+ * @return     `< 0` if an illegal value for @p rounds or @p keylen was suppplied.
  */
 int chacha_init(chacha_ctx *ctx,
                 unsigned rounds,
@@ -130,6 +130,8 @@ void chacha_prng_seed(const void *data, size_t bytes);
  *
  * @warning After you have read 2^68 numbers you have to re-seed the PRNG.
  *          Otherwise the sequence will repeat.
+ *
+ * @return The random value
  */
 uint32_t chacha_prng_next(void);
 

sys/include/crypto/ciphers.h

@@ -125,8 +125,11 @@ typedef struct {
  * @param key_size   length of the encryption key
  *
  * @return  CIPHER_INIT_SUCCESS if the initialization was successful.
- *          The command may be unsuccessful if the key size is not valid.
+ * @return  CIPHER_ERR_BAD_CONTEXT_SIZE if CIPHER_MAX_CONTEXT_SIZE has not
- *          CIPHER_ERR_BAD_CONTEXT_SIZE if CIPHER_MAX_CONTEXT_SIZE has not been defined (which means that the cipher has not been included in the build)
+ *          been defined (which means that the cipher has not been included
+ *          in the build)
+ * @return  The command may return CIPHER_ERR_INVALID_KEY_SIZE if the
+ *          key size is not valid.
  */
 int cipher_init(cipher_t* cipher, cipher_id_t cipher_id, const uint8_t* key,
                 uint8_t key_size);
@@ -140,6 +143,10 @@ int cipher_init(cipher_t* cipher, cipher_id_t cipher_id, const uint8_t* key,
  * @param input      pointer to input data to encrypt
  * @param output     pointer to allocated memory for encrypted data. It has to
  *                   be of size BLOCK_SIZE
+ *
+ * @return           The result of the encrypt operation of the underlying
+ *                   cipher, which is always 1 in case of success
+ * @return           A negative value for an error
  */
 int cipher_encrypt(const cipher_t* cipher, const uint8_t* input, uint8_t* output);
 
@@ -152,6 +159,10 @@ int cipher_encrypt(const cipher_t* cipher, const uint8_t* input, uint8_t* output
  * @param input      pointer to input data (of size BLOCKS_SIZE) to decrypt
  * @param output     pointer to allocated memory for decrypted data. It has to
  *                   be of size BLOCK_SIZE
+ *
+ * @return           The result of the decrypt operation of the underlying
+ *                   cipher, which is always 1 in case of success
+ * @return           A negative value for an error
  */
 int cipher_decrypt(const cipher_t* cipher, const uint8_t* input, uint8_t* output);
 
@@ -161,6 +172,8 @@ int cipher_decrypt(const cipher_t* cipher, const uint8_t* input, uint8_t* output
  * *
  *
  * @param cipher     Already initialized cipher struct
+ *
+ * @return           The cipher's block size (in bytes)
  */
 int cipher_get_block_size(const cipher_t* cipher);
 

sys/include/crypto/modes/ccm.h

@@ -54,7 +54,8 @@ extern "C" {
  * @param input_len        length of the input data
  * @param output           pointer to allocated memory for encrypted data. It
  *                         has to be of size data_len + mac_length.
- * @return                 length of encrypted data or error code
+ * @return                 Length of encrypted data on a successful encryption
+ * @return                 A negative error code if something went wrong
  */
 int cipher_encrypt_ccm(cipher_t* cipher, uint8_t* auth_data,
                        uint32_t auth_data_len, uint8_t mac_length,
@@ -79,7 +80,9 @@ int cipher_encrypt_ccm(cipher_t* cipher, uint8_t* auth_data,
  * @param input_len        length of the input data
  * @param output           pointer to allocated memory for decrypted data. It
  *                         has to be of size data_len - mac_length.
- * @return                 length of encrypted data or error code
+ * 
+ * @return                 Length of the decrypted data on a successful decryption
+ * @return                 A negative error code if something went wrong
  */
 int cipher_decrypt_ccm(cipher_t* cipher, uint8_t* auth_data,
                        uint32_t auth_data_len, uint8_t mac_length,

sys/include/crypto/modes/ctr.h

@@ -40,6 +40,9 @@ extern "C" {
  * @param length        length of the input data
  * @param output        pointer to allocated memory for encrypted data. It has
  *                      to be of size data_len.
+ * 
+ * @return              Length of encrypted data on a successful encryption
+ * @return              A negative error code if something went wrong
  */
 int cipher_encrypt_ctr(cipher_t* cipher, uint8_t nonce_counter[16],
                        uint8_t nonce_len, uint8_t* input, size_t length,
@@ -61,6 +64,10 @@ int cipher_encrypt_ctr(cipher_t* cipher, uint8_t nonce_counter[16],
  * @param length        length of the input data
  * @param output        pointer to allocated memory for encrypted data. It has
  *                      to be of size data_len.
+ * 
+ * @return              Length of decrypted data on a successful decryption
+ * @return              A negative error code if something went wrong
+ * 
  */
 int cipher_decrypt_ctr(cipher_t* cipher, uint8_t nonce_counter[16],
                        uint8_t nonce_len, uint8_t* input, size_t length,

sys/include/crypto/modes/ecb.h

@@ -37,6 +37,10 @@ extern "C" {
  * @param length     length of the input data
  * @param output     pointer to allocated memory for encrypted data. It has to
  *                   be of size data_len + BLOCK_SIZE - data_len % BLOCK_SIZE.
+ * 
+ * @return           Length of encrypted data on a successful encryption
+ * @return           A negative error code if something went wrong
+ *
  */
 int cipher_encrypt_ecb(cipher_t* cipher, uint8_t* input, size_t length,
                        uint8_t* output);
@@ -51,6 +55,10 @@ int cipher_encrypt_ecb(cipher_t* cipher, uint8_t* input, size_t length,
  * @param length     length of the input data
  * @param output     pointer to allocated memory for plaintext data. It has to
  *                   be of size `lengh`.
+ * 
+ * @return           Length of decrypted data on a successful decryption
+ * @return           A negative error code if something went wrong
+ * 
  */
 int cipher_decrypt_ecb(cipher_t* cipher, uint8_t* input, size_t length,
                        uint8_t* output);