riot-ci/RIOT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

crypto: Improve and fix comments

Browse Source 
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
This commit is contained in:
Mathias Tausig 2018-10-13 23:04:23 +02:00 committed by Mathias Tausig
parent 3ddd17b267
commit 41667cef66
6 changed files with 51 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
sys/include/crypto/aes.h
View File

@ -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);

6
sys/include/crypto/chacha.h
View File

@ -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.
* @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,
@ -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);

17
sys/include/crypto/ciphers.h
View File

@ -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);

7
sys/include/crypto/modes/ccm.h
View File

@ -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,

7
sys/include/crypto/modes/ctr.h
View File

@ -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,

8
sys/include/crypto/modes/ecb.h
View File

@ -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);