Merge pull request #5908 from mtausig/ciphers_doc

ciphers: Documented return values of init functions

sys/crypto/3des.c

@@ -259,7 +259,7 @@ int tripledes_init(cipher_context_t *context, const uint8_t *key,
     // Make sure that context is large enough. If this is not the case,
     // you should build with -DTHREEDES
     if(CIPHER_MAX_CONTEXT_SIZE < THREEDES_MAX_KEY_SIZE) {
-        return 0;
+        return CIPHER_ERR_BAD_CONTEXT_SIZE;
     }
 
     //key must be at least 24 Bytes long
@@ -275,7 +275,7 @@ int tripledes_init(cipher_context_t *context, const uint8_t *key,
         }
     }
 
-    return 1;
+    return CIPHER_INIT_SUCCESS;
 }
 
 int tripledes_encrypt(const cipher_context_t *context, const uint8_t *plain, uint8_t *crypt)

sys/crypto/aes.c

@@ -727,7 +727,7 @@ int aes_init(cipher_context_t *context, const uint8_t *key, uint8_t keySize)
     // Make sure that context is large enough. If this is not the case,
     // you should build with -DAES
     if(CIPHER_MAX_CONTEXT_SIZE < AES_KEY_SIZE) {
-        return 0;
+        return CIPHER_ERR_BAD_CONTEXT_SIZE;
     }
 
     //key must be at least CIPHERS_MAX_KEY_SIZE Bytes long
@@ -743,7 +743,7 @@ int aes_init(cipher_context_t *context, const uint8_t *key, uint8_t keySize)
         }
     }
 
-    return 1;
+    return CIPHER_INIT_SUCCESS;
 }
 
 /**

sys/crypto/twofish.c

@@ -483,7 +483,7 @@ int twofish_init(cipher_context_t *context, const uint8_t *key,
     // Make sure that context is large enough. If this is not the case,
     // you should build with -DTWOFISH.
     if(CIPHER_MAX_CONTEXT_SIZE < TWOFISH_CONTEXT_SIZE) {
-        return 0;
+        return CIPHER_ERR_BAD_CONTEXT_SIZE;
     }
 
     //key must be at least CIPHERS_MAX_KEY_SIZE Bytes long
@@ -499,7 +499,7 @@ int twofish_init(cipher_context_t *context, const uint8_t *key,
         }
     }
 
-    return 1;
+    return CIPHER_INIT_SUCCESS;
 }
 
 /**

sys/include/crypto/3des.h

@@ -85,8 +85,9 @@ static const uint32_t bigbyte[24] = {
  * @param   keySize     the size of the key
 
  *
- * @return  Whether initialization was successful. The command may be
- *          unsuccessful if the key size is not valid.
+ * @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)
  */
 int tripledes_init(cipher_context_t *context, const uint8_t* key, uint8_t keySize);
 

sys/include/crypto/aes.h

@@ -80,8 +80,9 @@ typedef struct {
  * @param       keySize   the size of the key
  * @param       key       a pointer to the key
  *
- * @return  Whether initialization was successful. The command may be
- *          unsuccessful if the key size is not valid.
+ * @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)
  */
 int aes_init(cipher_context_t *context, const uint8_t *key, uint8_t keySize);
 

sys/include/crypto/ciphers.h

@@ -61,13 +61,16 @@ extern "C" {
     #define CIPHER_MAX_CONTEXT_SIZE 1
 #endif
 
-/**
- * error codes
- */
+/* return codes */
+
 #define CIPHER_ERR_INVALID_KEY_SIZE   -3
 #define CIPHER_ERR_INVALID_LENGTH     -4
 #define CIPHER_ERR_ENC_FAILED         -5
 #define CIPHER_ERR_DEC_FAILED         -6
+/** Is returned by the cipher_init functions, if the coresponding alogirithm has not been included in the build */
+#define CIPHER_ERR_BAD_CONTEXT_SIZE    0
+/**  Returned by cipher_init upon succesful initialization of a cipher. */
+#define CIPHER_INIT_SUCCESS            1
 
 /**
  * @brief   the context for cipher-operations
@@ -126,6 +129,10 @@ typedef struct {
  * @param cipher_id  cipher algorithm id
  * @param key        encryption key to use
  * @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)
  */
 int cipher_init(cipher_t* cipher, cipher_id_t cipher_id, const uint8_t* key,
                 uint8_t key_size);

sys/include/crypto/twofish.h

@@ -222,8 +222,9 @@ typedef struct {
  * @param   key_size    key size in bytes
  * @param   key         pointer to the key
  *
- * @return  Whether initialization was successful. The command may be
- *          unsuccessful if the key size is not valid.
+ * @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)
  */
 int twofish_init(cipher_context_t *context, const uint8_t *key, uint8_t key_size);