adding documentation

[avr-crypto-lib.git] / cast5.h

diff --git a/cast5.h b/cast5.h
index 717c5d7b7a9e1ac7059e115d1b8016581f7bbff0..aa81ca19a8fb0f5308ccd440363796f937c87938 100644 (file)
--- a/cast5.h
+++ b/cast5.h
@@ -24,6 +24,16 @@
  * Description: Implementation of the CAST5 (aka CAST-128) cipher algorithm as described in RFC 2144
  * 
  */
+
+/** 
+ * \file       cast5.h
+ * \author     Daniel Otte
+ * \date       2006-07-26
+ * \license GPL
+ * \brief Implementation of the CAST5 (aka CAST-128) cipher algorithm as described in RFC 2144
+ * 
+ */
+
 #ifndef CAST5_H_
 #define CAST5_H_ 
 
@@ -40,7 +50,13 @@
  #endif
 #endif
 
-
+/** \typedef cast5_ctx_t
+ * \brief CAST-5 context
+ * 
+ * A variable of this type may hold a keyschedule for the CAST-5 cipher. 
+ * This context is regulary generated by the 
+ * cast5_init(uint8_t* key, uint8_t keylength_b, cast5_ctx_t* s) funtion.
+ */
 typedef struct cast5_ctx_st{
        uint32_t        mask[16];
        uint8_t         rotl[8];        /* 4 bit from every rotation key is stored here */
@@ -48,9 +64,39 @@ typedef struct cast5_ctx_st{
        bool            shortkey;
 } cast5_ctx_t;
 
-void cast5_init(uint8_t* key, uint8_t keylength_b, cast5_ctx_t* s);
-void cast5_enc(void* block, cast5_ctx_t *s);
-void cast5_dec(void* block, cast5_ctx_t *s);
+
+/** \fn void cast5_init(void* key, uint8_t keylength_b, cast5_ctx_t* s);
+ * \brief generate keyschedule/contex for CAST-5
+ * 
+ * This function generates the keyschedule from the supplied key for the 
+ * CAST-5 cipher and stores it in a supplied ::cast5_ctx_t context.
+ * \param key pointer to the key
+ * \param keylength_b length of the key in bits (maximum 128 bits)
+ * \param s pointer to the context
+ */
+void cast5_init(void* key, uint8_t keylength_b, cast5_ctx_t* s);
+
+/** \fn void cast5_enc(void* block, const cast5_ctx_t *s);
+ * \brief encrypt a block with the CAST-5 algorithm
+ * 
+ * This function encrypts a block of 64 bits (8 bytes) with the CAST-5 algorithm.
+ * It uses a keyschedule as generated by the 
+ * cast5_init(void* key, uint8_t keylength_b, cast5_ctx_t* s) function.
+ * \param block pointer to the block which gets encrypted
+ * \param s pointer to the keyschedule/context
+ */
+void cast5_enc(void* block, const cast5_ctx_t *s);
+
+/** \fn void cast5_dec(void* block, const cast5_ctx_t *s);
+ * \brief decrypt a block with the CAST-5 algorithm
+ * 
+ * This function decrypts a block of 64 bits (8 bytes) with the CAST-5 algorithm.
+ * It uses a keyschedule as generated by the 
+ * cast5_init(void* key, uint8_t keylength_b, cast5_ctx_t* s) function.
+ * \param block pointer to the block which gets decrypted
+ * \param s pointer to the keyschedule/context
+ */
+void cast5_dec(void* block, const cast5_ctx_t *s);