diff --git a/sys/include/crypto/aes.h b/sys/include/crypto/aes.h
index 959321cac119207b33d83b4fd8ab5c6ffc6857a0..6a897348684df81fa12a300240d55e6a463d833c 100644
--- a/sys/include/crypto/aes.h
+++ b/sys/include/crypto/aes.h
@@ -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
- * of the cipher in
+ * @param context the cipher_context_t-struct to save the
+ * 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.
- * 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)
+ * @return 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)
*/
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
- * decryption key schedule
+ * @return 1 on success
+ * @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);
diff --git a/sys/include/crypto/chacha.h b/sys/include/crypto/chacha.h
index ca89cc79ff4a10aff155d229482794952e4a5910..9047efa2c5fa64ed3c4842be8434bd2e27e3ea15 100644
--- a/sys/include/crypto/chacha.h
+++ b/sys/include/crypto/chacha.h
@@ -59,8 +59,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.
- * @returns `< 0` if an illegal value for @p rounds or @p keylen was suppplied.
+ * @return `== 0` on success.
+ * @return `< 0` if an illegal value for @p rounds or @p keylen was suppplied.
*/
int chacha_init(chacha_ctx *ctx,
unsigned rounds,
@@ -73,7 +73,7 @@ int chacha_init(chacha_ctx *ctx,
* @details If you want to seek inside the cipher steam, then you have to
* update the clock in `ctx->state[13]:ctx->state[12]` manually.
*
- * @warning You need to re-initialized the context with a new nonce after 2^64
+ * @warning You need to re-initialize the context with a new nonce after 2^64
* encrypted blocks, or the keystream will repeat!
*
* @param[in,out] ctx The ChaCha context
@@ -87,7 +87,7 @@ void chacha_keystream_bytes(chacha_ctx *ctx, void *x);
* @details @p m is always the input regardless if it is the plaintext or ciphertext,
* and @p c vice verse.
*
- * @warning You need to re-initialized the context with a new nonce after 2^64
+ * @warning You need to re-initialize the context with a new nonce after 2^64
* encrypted blocks, or the keystream will repeat!
*
* @param[in,out] ctx The ChaCha context.
@@ -129,6 +129,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);
diff --git a/sys/include/crypto/ciphers.h b/sys/include/crypto/ciphers.h
index ea0ce1c0968a5302f93d19b9e961c50919a21352..0ad00d3f4337c292c43d2fadede03eb5612d12da 100644
--- a/sys/include/crypto/ciphers.h
+++ b/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.
- * 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)
+ * @return 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)
+ * @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);
diff --git a/sys/include/crypto/modes/ccm.h b/sys/include/crypto/modes/ccm.h
index b61c2d12386e956c5de92b16fd6c1081c1b439c1..03ac25a5f15b3b7b008c44c284e3c4063c9d1480 100644
--- a/sys/include/crypto/modes/ccm.h
+++ b/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,
diff --git a/sys/include/crypto/modes/ctr.h b/sys/include/crypto/modes/ctr.h
index 7c5b493fefa655a947a0f8fd4cc9a8d2ea3e2405..36d2aefd1d0b18c398d6b181113950d7dc16dfa3 100644
--- a/sys/include/crypto/modes/ctr.h
+++ b/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,9 @@ 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,
diff --git a/sys/include/crypto/modes/ecb.h b/sys/include/crypto/modes/ecb.h
index 4e04067c282ec34de81526070adf08f044bcd67a..08a19e7f7a80b9545695500f11291b4f66eb32d2 100644
--- a/sys/include/crypto/modes/ecb.h
+++ b/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,9 @@ 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);
diff --git a/sys/include/hashes/sha3.h b/sys/include/hashes/sha3.h
index 350924b17106e8669417be9eab1684a237676675..bc1b9e2d7c600b0906ac3a82493d532ad7373955 100644
--- a/sys/include/hashes/sha3.h
+++ b/sys/include/hashes/sha3.h
@@ -3,7 +3,7 @@
* Joan Daemen, Michaël Peeters, Gilles Van Assche and Ronny Van Keer, hereby
* denoted as "the implementer".
*
- * RIOT-OS adaptaion by Mathias Tausig
+ * RIOT-OS adaptation by Mathias Tausig
*
* This software is released under the Creative Commons CC0 1.0 license.
* To the extent possible under law, the implementer has waived all copyright