From 4d76909e4282baf1420ee309e270384246b241b8 Mon Sep 17 00:00:00 2001 From: bg Date: Sat, 2 Aug 2008 04:38:17 +0000 Subject: [PATCH] adding documentation --- A5_1.h | 6 ++-- Doxyfile | 10 +++--- Makefile | 6 ++-- arcfour-asm.S | 1 + arcfour.c | 31 ++++++++-------- arcfour.h | 56 ++++++++++++++++++++++++----- cast5.c | 23 +++--------- cast5.h | 54 +++++++++++++++++++++++++--- des.c | 48 ++++++++++++------------- des.h | 72 +++++++++++++++++++++++++++++++++---- entropium.c | 88 +++++++++++++--------------------------------- entropium.h | 43 +++++++++++++++++++++- main-shabea-test.c | 6 ++-- main.dox | 57 ++++++++++++++++++++++++++++++ 14 files changed, 344 insertions(+), 157 deletions(-) create mode 100644 main.dox diff --git a/A5_1.h b/A5_1.h index 95f345c..1c85750 100644 --- a/A5_1.h +++ b/A5_1.h @@ -17,9 +17,9 @@ along with this program. If not, see . */ /* - * File: A5_1.h - * Author: Daniel Otte - * Date: 24.06.2006 + * File: A5_1.h + * Author: Daniel Otte + * Date: 24.06.2006 * License: GPL * Description: Implementation of the A5/1 stream cipher algorithm, as used in GSM. * ! Warning, this is weak crypto ! diff --git a/Doxyfile b/Doxyfile index 2d42cc6..3eed9fc 100644 --- a/Doxyfile +++ b/Doxyfile @@ -34,7 +34,7 @@ DETAILS_AT_TOP = NO INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 8 -ALIASES = +ALIASES = "license=\par License:\n" "email=\par E-Mail:\n" OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO BUILTIN_STL_SUPPORT = NO @@ -127,7 +127,7 @@ FILE_PATTERNS = *.c \ RECURSIVE = NO EXCLUDE = EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = main-* EXAMPLE_PATH = EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO @@ -248,16 +248,16 @@ PERL_PATH = /usr/bin/perl CLASS_DIAGRAMS = NO HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES -CLASS_GRAPH = YES +CLASS_GRAPH = NO COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES UML_LOOK = NO TEMPLATE_RELATIONS = NO INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES -CALL_GRAPH = YES +CALL_GRAPH = NO CALLER_GRAPH = NO -GRAPHICAL_HIERARCHY = YES +GRAPHICAL_HIERARCHY = NO DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png DOT_PATH = diff --git a/Makefile b/Makefile index efae2b4..8033ad2 100644 --- a/Makefile +++ b/Makefile @@ -183,9 +183,9 @@ clean: xclean: clean rm -rf $(DEP_DIR)*.d -flash: - $(ERASECMD) - $(FLASHCMD) +docu: + doxygen + %.lst: %.elf $(OBJDUMP) -h -S $< > $@ diff --git a/arcfour-asm.S b/arcfour-asm.S index ec0eeeb..d3ecadb 100644 --- a/arcfour-asm.S +++ b/arcfour-asm.S @@ -16,6 +16,7 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . */ + /* * File: arcfour-asm.S * Author: Daniel Otte diff --git a/arcfour.c b/arcfour.c index f8d01a6..13fb159 100644 --- a/arcfour.c +++ b/arcfour.c @@ -33,30 +33,29 @@ * length is length of key in bytes! */ -void arcfour_init(arcfour_ctx_t *c, uint8_t *key, uint8_t length){ +void arcfour_init(arcfour_ctx_t *ctx, void *key, uint8_t length_B){ uint8_t t; unsigned x,y=0; for(x=0; x<= 255; ++x) - c->s[x]=x; + ctx->s[x]=x; for(x=0; x<= 255; ++x){ - y += c->s[x] + key[x % length]; + y += ctx->s[x] + ((uint8_t*)key)[x % length_B]; y &= 0xff; - t = c->s[y]; - c->s[y] = c->s[x]; - c->s[x] = t; - }; - - c->i = c->j = 0; + t = ctx->s[y]; + ctx->s[y] = ctx->s[x]; + ctx->s[x] = t; + } + ctx->i = ctx->j = 0; } -uint8_t arcfour_gen(arcfour_ctx_t *c){ +uint8_t arcfour_gen(arcfour_ctx_t *ctx){ uint8_t t; - c->i++; - c->j += c->s[c->i]; - t = c->s[c->j]; - c->s[c->j] = c->s[c->i]; - c->s[c->i] = t; - return c->s[(c->s[c->j] + c->s[c->i]) & 0xff]; + ctx->i++; + ctx->j += ctx->s[ctx->i]; + t = ctx->s[ctx->j]; + ctx->s[ctx->j] = ctx->s[ctx->i]; + ctx->s[ctx->i] = t; + return ctx->s[(ctx->s[ctx->j] + ctx->s[ctx->i]) & 0xff]; } diff --git a/arcfour.h b/arcfour.h index 38ab40d..1f5af2f 100644 --- a/arcfour.h +++ b/arcfour.h @@ -20,16 +20,22 @@ * File: arcfour.h * Author: Daniel Otte * Date: 2006-06-07 - * License: GPL + * License: GPLv3+ * Description: Implementation of the ARCFOUR (RC4 compatible) stream cipher algorithm. */ -/* + +/** * \file arcfour.h * \author Daniel Otte * \date 2006-06-07 - * \par License - * GPL - * \brief Implementation of the ARCFOUR (RC4 compatible) stream cipher algorithm. + * \license GPLv3+ + * \brief Implementation of the ARCFOUR (RC4 compatible) stream cipher algorithm. + * + * This header file defines the interface of the ARCFOUR cipher implementation. + * + * This implementation aims to be compatible with the ARCFOUR description + * availabe at + * http://www.mozilla.org/projects/security/pki/nss/draft-kaukonen-cipher-arcfour-03.txt */ @@ -38,14 +44,48 @@ #include -typedef struct { +/** \typedef arcfour_ctx_t + * \brief type for arcfour context + * + * A variable of this type may contain a complete ARCFOUR context. + * The context is used to store the state of the cipher and gets + * created by the arcfour_init(arcfour_ctx_t *c, uint8_t *key, uint8_t length_B) + * function. The context is of the fixed size of 258 bytes + */ + +/** \struct arcfour_ctx_st + * \brief base for ::arcfour_ctx_t + * + * The struct holds the two indices and the S-Box + */ +typedef struct arcfour_ctx_st { uint8_t i,j; uint8_t s[256]; } arcfour_ctx_t; +/** \fn void arcfour_init(arcfour_ctx_t *ctx, void *key, uint8_t length_B) + * \brief setup a context with a key + * + * This function sets up a ::arcfour_ctx_t context using + * the supplied key of the given length. + * \param ctx pointer to the context + * \param key pointer to the key + * \param length_B length of the key in bytes (between 1 and 255) + */ + +void arcfour_init(arcfour_ctx_t *ctx, void *key, uint8_t length_B); -void arcfour_init(arcfour_ctx_t *c, uint8_t *key, uint8_t length); -uint8_t arcfour_gen(arcfour_ctx_t *c); +/** \fn uint8_t arcfour_gen(arcfour_ctx_t *ctx) + * \brief generates a byte of keystream + * + * This function generates the next byte of keystream + * from the supplied ::arcfour_ctx_t context which is updated acordingly + * + * \param ctx pointer to the context + * \return byte of keystream + */ + +uint8_t arcfour_gen(arcfour_ctx_t *ctx); #endif diff --git a/cast5.c b/cast5.c index 8a71e6d..0ed3ddf 100644 --- a/cast5.c +++ b/cast5.c @@ -107,13 +107,8 @@ void cast5_init_rM(uint8_t *klo, uint8_t *khi, uint8_t offset, uint8_t *src, boo -/** - * \brief sets up round keys (context) for cast5 en/decryption. - * @param s Pointer to cast5 context. - * @param key Pointer to binary key. - * @param keylength length of keydata in bits. - */ -void cast5_init(uint8_t* key, uint8_t keylength_b, cast5_ctx_t* s){ + +void cast5_init(void* key, uint8_t keylength_b, cast5_ctx_t* s){ /* we migth return if the key is valid and if setup was sucessfull */ uint32_t x[4], z[4]; #define BPX ((uint8_t*)&(x[0])) @@ -270,12 +265,7 @@ uint32_t cast5_f3(uint32_t d, uint32_t m, uint8_t r){ /*************************************************************************/ -/** - * \brief encrypts a datablock with cast5 - * @param block Pointer to datablock - * @param s Pointer to cast5 roundkeys (context) - */ -void cast5_enc(void* block, cast5_ctx_t *s){ +void cast5_enc(void* block, const cast5_ctx_t *s){ uint32_t l,r, x, y; uint8_t i; cast5_f_t* f[]={cast5_f1,cast5_f2,cast5_f3}; @@ -299,12 +289,7 @@ void cast5_enc(void* block, cast5_ctx_t *s){ /*************************************************************************/ -/** - * \brief decrypts a datablock with cast5 - * @param block Pointer to datablock - * @param s Pointer to cast5 roundkeys (context) - */ -void cast5_dec(void* block, cast5_ctx_t *s){ +void cast5_dec(void* block, const cast5_ctx_t *s){ uint32_t l,r, x, y; int8_t i, rounds; cast5_f_t* f[]={cast5_f1,cast5_f2,cast5_f3}; diff --git a/cast5.h b/cast5.h index 717c5d7..aa81ca1 100644 --- 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); diff --git a/des.c b/des.c index 33e6a76..4a5277e 100644 --- a/des.c +++ b/des.c @@ -17,18 +17,18 @@ along with this program. If not, see . */ /** - * \file des.c - * \author Daniel Otte - * \email daniel.otte@rub.de - * \date 2007-06-16 - * \brief DES and EDE-DES implementation - * \par License - * GPLv3 or later + * \file des.c + * \author Daniel Otte + * \email daniel.otte@rub.de + * \date 2007-06-16 + * \brief DES and EDE-DES implementation + * \license GPLv3 or later * */ #include "config.h" #include "debug.h" #include "uart.h" +#include #include #include #include @@ -207,7 +207,7 @@ prog_uint8_t shiftkeyinv_permtab[] = { #define ROTTABLE_INV 0x3F7E /******************************************************************************/ -void permute(prog_uint8_t *ptable, uint8_t *in, uint8_t *out){ +void permute(prog_uint8_t *ptable, const uint8_t *in, uint8_t *out){ uint8_t ib, ob; /* in-bytes and out-bytes */ uint8_t byte, bit; /* counter for bit and byte */ ib = pgm_read_byte(&(ptable[0])); @@ -302,15 +302,15 @@ uint32_t des_f(uint32_t r, uint8_t* kr){ /******************************************************************************/ -void des_enc(uint8_t* out, uint8_t* in, uint8_t* key){ +void des_enc(void* out, const void* in, const void* key){ #define R *((uint32_t*)&(data[4])) #define L *((uint32_t*)&(data[0])) uint8_t data[8],kr[6],k[7]; uint8_t i; - permute((prog_uint8_t*)ip_permtab, in, data); - permute((prog_uint8_t*)pc1_permtab, key, k); + permute((prog_uint8_t*)ip_permtab, (uint8_t*)in, data); + permute((prog_uint8_t*)pc1_permtab, (uint8_t*)key, k); for(i=0; i<8; ++i){ shiftkey(k); if(ROTTABLE&((1<<((i<<1)+0))) ) @@ -330,20 +330,20 @@ void des_enc(uint8_t* out, uint8_t* in, uint8_t* key){ L ^= R; R ^= L; - permute((prog_uint8_t*)inv_ip_permtab, data, out); + permute((prog_uint8_t*)inv_ip_permtab, data, (uint8_t*)out); } /******************************************************************************/ -void des_dec(uint8_t* out, uint8_t* in, uint8_t* key){ +void des_dec(void* out, const void* in, const uint8_t* key){ #define R *((uint32_t*)&(data[4])) #define L *((uint32_t*)&(data[0])) uint8_t data[8],kr[6],k[7]; int8_t i; - permute((prog_uint8_t*)ip_permtab, in, data); - permute((prog_uint8_t*)pc1_permtab, key, k); + permute((prog_uint8_t*)ip_permtab, (uint8_t*)in, data); + permute((prog_uint8_t*)pc1_permtab, (uint8_t*)key, k); for(i=7; i>=0; --i){ permute((prog_uint8_t*)pc2_permtab, k, kr); @@ -366,23 +366,23 @@ void des_dec(uint8_t* out, uint8_t* in, uint8_t* key){ L ^= R; R ^= L; - permute((prog_uint8_t*)inv_ip_permtab, data, out); + permute((prog_uint8_t*)inv_ip_permtab, data, (uint8_t*)out); } /******************************************************************************/ -void tdes_enc(uint8_t* out, uint8_t* in, uint8_t* key){ - des_enc(out, in, key + 0); - des_dec(out, out, key + 8); - des_enc(out, out, key +16); +void tdes_enc(void* out, void* in, const void* key){ + des_enc(out, in, (uint8_t*)key + 0); + des_dec(out, out, (uint8_t*)key + 8); + des_enc(out, out, (uint8_t*)key +16); } /******************************************************************************/ -void tdes_dec(uint8_t* out, uint8_t* in, uint8_t* key){ - des_dec(out, in, key + 0); - des_enc(out, out, key + 8); - des_dec(out, out, key +16); +void tdes_dec(void* out, void* in, const uint8_t* key){ + des_dec(out, in, (uint8_t*)key + 0); + des_enc(out, out, (uint8_t*)key + 8); + des_dec(out, out, (uint8_t*)key +16); } /******************************************************************************/ diff --git a/des.h b/des.h index 61bcd36..456dee1 100644 --- a/des.h +++ b/des.h @@ -21,22 +21,80 @@ * \author Daniel Otte * \date 2007-06-16 * \brief des and tdes declarations - * \par License - * GPL + * \license GPLv3 or later * */ #ifndef DES_H_ #define DES_H_ -#include /* the FIPS 46-3 (1999-10-25) name for triple DES is triple data encryption algorithm so TDEA. * Also we only implement the three key mode */ + +/** \def tdea_enc + * \brief defining an alias for void tdes_enc(void* out, const void* in, const void* key) + */ + +/** \def tdea_dec + * \brief defining an alias for void tdes_dec(void* out, const void* in, const void* key) + */ + #define tdea_enc tdes_enc #define tdea_dec tdes_dec -void des_enc(uint8_t* out, uint8_t* in, uint8_t* key); -void des_dec(uint8_t* out, uint8_t* in, uint8_t* key); -void tdes_enc(uint8_t* out, uint8_t* in, uint8_t* key); -void tdes_dec(uint8_t* out, uint8_t* in, uint8_t* key); +/** \fn void des_enc(void* out, const void* in, const void* key) + * \brief encrypt a block with DES + * + * This function encrypts a block of 64 bits (8 bytes) with the DES algorithm. + * Key expansion is done automatically. The key is 64 bits long, but note that + * only 56 bits are used (the LSB of each byte is droped). The input and output + * blocks may overlap. + * + * \param out pointer to the block (64 bit = 8 byte) where the ciphertext is written to + * \param in pointer to the block (64 bit = 8 byte) where the plaintext is read from + * \param key pointer to the key (64 bit = 8 byte) + */ +void des_enc(void* out, const void* in, const void* key); + +/** \fn void des_dec(void* out, const void* in, const void* key) + * \brief decrypt a block with DES + * + * This function decrypts a block of 64 bits (8 bytes) with the DES algorithm. + * Key expansion is done automatically. The key is 64 bits long, but note that + * only 56 bits are used (the LSB of each byte is droped). The input and output + * blocks may overlap. + * + * \param out pointer to the block (64 bit = 8 byte) where the plaintext is written to + * \param in pointer to the block (64 bit = 8 byte) where the ciphertext is read from + * \param key pointer to the key (64 bit = 8 byte) + */ +void des_dec(void* out, const void* in, const void* key); + +/** \fn void tdes_enc(void* out, const void* in, const void* key) + * \brief encrypt a block with Tripple-DES + * + * This function encrypts a block of 64 bits (8 bytes) with the Tripple-DES (EDE) + * algorithm. Key expansion is done automatically. The key is 192 bits long, but + * note that only 178 bits are used (the LSB of each byte is droped). The input + * and output blocks may overlap. + * + * \param out pointer to the block (64 bit = 8 byte) where the ciphertext is written to + * \param in pointer to the block (64 bit = 8 byte) where the plaintext is read from + * \param key pointer to the key (192 bit = 24 byte) + */ +void tdes_enc(void* out, const void* in, const void* key); + +/** \fn void tdes_dec(void* out, const void* in, const void* key) + * \brief decrypt a block with Tripple-DES + * + * This function decrypts a block of 64 bits (8 bytes) with the Tripple-DES (EDE) + * algorithm. Key expansion is done automatically. The key is 192 bits long, but + * note that only 178 bits are used (the LSB of each byte is droped). The input + * and output blocks may overlap. + * + * \param out pointer to the block (64 bit = 8 byte) where the plaintext is written to + * \param in pointer to the block (64 bit = 8 byte) where the ciphertext is read from + * \param key pointer to the key (192 bit = 24 byte) + */ + void tdes_dec(void* out, const void* in, const void* key); #endif /*DES_H_*/ diff --git a/entropium.c b/entropium.c index fdbf13c..625e468 100644 --- a/entropium.c +++ b/entropium.c @@ -17,53 +17,33 @@ along with this program. If not, see . */ /** - * \file entropium.c - * \author Daniel Otte - * \email daniel.otte@rub.de - * \date 2006-05-17 - * \par License: - * GPLv3 or later + * \file entropium.c + * \author Daniel Otte + * \email daniel.otte@rub.de + * \date 2006-05-17 + * \license GPLv3 or later * \brief This file contains an implementaition of a pseudo-random-number generator. * * Extension 1: * rndCore is expanded to 512 bits for more security. * - * \verbatim - * ################################################################################################ - * # # - * # +---------------------------+ # - * # | | +---+ # - * # V | | | # - * # (concat) | | V # - * +---------------+ # o---------o (xor)+---------+ o---------o | o----o o---------o # +--------------+ - * | entropy Block | -----> | sha-256 | --(offset)-< | rndCore | ---> | sha-256 | --+--+-| +1 |---> | sha-256 | -----> | random Block | - * +---------------+ # o---------o (xor)+---------+ o---------o | o----o o---------o # +--------------+ - * # (xor) (xor) | # - * # ^ ^ | # - * # \ / | # - * # (offset)---------------------+ # - * # # - * ################################################################################################ - * \endverbatim - */ - - /* \verbatim - * ################################################################################################ - * # # - * # +---------------------------+ # - * # | | +---+ # - * # V | | | # - * # (concat) | | V # - * +---------------+ # o---------o (xor)+---------+ o---------o | o----o o---------o # +--------------+ - * | entropy Block | -----> | sha-256 | --(offset)-< | rndCore | ---> | sha-256 | --+--+-| +1 |---> | sha-256 | -----> | random Block | - * +---------------+ # o---------o (xor)+---------+ o---------o | o----o o---------o # +--------------+ - * # (xor) (xor) | # - * # ^ ^ | # - * # \ / | # - * # (offset)---------------------+ # - * # # - * ################################################################################################ - * \endverbatim + \verbatim + ################################################################################################ + # # + # +---------------------------+ # + # | | # + # V | # + # (concat) | # + +---------------+ # o---------o (xor)+---------+ o---------o o----o o---------o # +--------------+ + | entropy Block | -----> | sha-256 | --(offset)-< | rndCore | ---> | sha-256 | --+----| +1 |---> | sha-256 | -----> | random Block | + +---------------+ # o---------o (xor)+---------+ o---------o | o----o o---------o # +--------------+ + # (xor) (xor) | # + # ^ ^ | # + # \ / | # + # (offset)---------------------+ # + # # + ################################################################################################ + \endverbatim */ #include @@ -79,12 +59,6 @@ uint32_t rndCore[16]; /*************************************************************************/ -/** - * \brief This function adds entropy to the central entropy pool - * - * @param length This ist the length of the random data in BITS. - * @param data This is the random data which should be added to the entropy pool -*/ /* idea is: hash the message and add it via xor to rndCore * * length in bits @@ -110,10 +84,7 @@ void entropium_addEntropy(unsigned length_b, const void* data){ } /*************************************************************************/ -/** - * \brief This function fills a given buffer with 32 random bytes - * @param b Pointer to buffer wich is to fill - */ + void entropium_getRandomBlock(void *b){ sha256_ctx_t s; uint8_t offset=8; @@ -133,11 +104,7 @@ void entropium_getRandomBlock(void *b){ } /*************************************************************************/ - -/** - * \brief This function simply returns a random byte - * @return a random byte - */ + uint8_t entropium_getRandomByte(void){ static uint8_t block[32]; static uint8_t i=32; @@ -149,13 +116,6 @@ uint8_t entropium_getRandomByte(void){ return block[i++]; } -/*************************************************************************/ - -/** - * \brief This function fills the given bock with length random bytes - * @return a random byte - */ - void entropium_fillBlockRandom(void* block, unsigned length_B){ while(length_B>ENTROPIUM_RANDOMBLOCK_SIZE){ entropium_getRandomBlock(block); diff --git a/entropium.h b/entropium.h index 02aa317..7b4081e 100644 --- a/entropium.h +++ b/entropium.h @@ -16,6 +16,7 @@ You should have received a copy of the GNU General Public License along with this program. If not, see . */ + /** * File: entropium.h * Author: Daniel Otte @@ -24,6 +25,15 @@ * Description: This file contains the declarations for the pseudo-random-number generator. **/ +/** + * \file entropium.h + * \author Daniel Otte + * \date 23.07.2006 + * \license GPLv3 or later + * \brief This file contains the declarations for the pseudo-random-number generator. + **/ + + #ifndef ENTROPIUM_H_ #define ENTROPIUM_H_ @@ -33,11 +43,42 @@ */ #define ENTROPIUM_RANDOMBLOCK_SIZE 32 /* bytes */ +/** \fn void entropium_addEntropy(unsigned length_b, const void* data) + * \brief add entropy to the prng + * + * This function adds data to the internal entropy pool + * \param length_b length of the data block in bits + * \param data pointer to the data + */ void entropium_addEntropy(unsigned length_b, const void* data); + +/** \fn void entropium_getRandomBlock(void* b) + * \brief generate a fixed size block of random data + * + * This function writes 32 bytes of random extracted from the entropy pool + * in the supplied buffer. + * \param b buffer where the random data gets written + */ void entropium_getRandomBlock(void* b); -/* this does some simple buffering */ + +/** \fn uint8_t entropium_getRandomByte(void) + * \brief get a single byte of random data + * + * This function utilizes a internal buffer which gets automatically filled + * again. + * \return a byte of random data + */ uint8_t entropium_getRandomByte(void); +/** \fn void entropium_fillBlockRandom(void* block, unsigned length_B) + * \brief get a block of random data + * + * This function writes random data extracted from the entropy pool in the + * supplied buffer. It shares a internal buffer with the + * entropium_getRandomByte() function. + * \param block pointer to the buffer where the random data goes + * \param length_B number of bytes to be written to the buffer + */ void entropium_fillBlockRandom(void* block, unsigned length_B); #endif /*PRNG_H_*/ diff --git a/main-shabea-test.c b/main-shabea-test.c index aadebd0..f221fd5 100644 --- a/main-shabea-test.c +++ b/main-shabea-test.c @@ -42,10 +42,10 @@ char* cipher_name = "Shabea"; /***************************************************************************** - * additional validation-functions * + * additional validation-functions * *****************************************************************************/ -void shabea_genctx_dummy(uint8_t* key, uint16_t keysize, void* ctx){ - memcpy(ctx, key, keysize); +void shabea_genctx_dummy(uint8_t* key, uint16_t keysize_b, void* ctx){ + memcpy(ctx, key, (keysize_b+7)/8); } void shabea_enc_dummy(void* buffer, void* ctx){ diff --git a/main.dox b/main.dox new file mode 100644 index 0000000..199a398 --- /dev/null +++ b/main.dox @@ -0,0 +1,57 @@ +/** \mainpage Documentation for microcrypt-lib + \section Algorithms Available algorithms + \subsection Stream-ciphers Stream ciphers + A stream cipher generates a keystream which is normaly XORed with the + plaintext to produce the the ciphertext. Stream ciphers therfore have a + state which is automaticaly updated to produce the next element of the + keystream. Most Streamciphers produce a fixed length of keytream per + iteration which may be a byte, a bit or any other data unit. + + Implemented stream ciphers: + - A5/1 (A5_1.h) + - ARCFOUR (RC4 compatible) (arcfour.h) + - Grain (grain.h) + - Trivium (trivium.h) + + \subsection Block-ciphers Block ciphers + Block cipher encrypt/decrypt fixed length blocks (mostly 64 bits or 128 bits) + with a key. Most block ciphers iterate a round function which uses a so-called + round key. The round keys are generated on the fly or with a special init + function (this is cipher specific). Round keys are stored in a context which + is not modifyed by the encryption or decryption function. Also the same + context can be used for encryption and decryption and depends only on the key + and its length. + + Implemented block ciphers: + - Camellia (camellia.h) + - CAST5 (a.k.a CAST-128) (cast5.h) + - CAST6 (a.k.a CAST-256) (cast6.h) + - DES & Tripple-DES (EDE) (des.h) + - Noekeon (noekeon.h) + - RC5 (rc5.h) + - RC6 (rc6.h) + - SEED (seed.h) + - Serpent (serpent.h) + - Shabea (shabea.h) + - SHACAL-1 (encryption only) (shacal1_enc.h) + - SHACAL-2 (encryption only) (shacal2_enc.h) + - Skipjack (skipjack.h) + - XTEA (xtea.h) + + \subsection Hashes Hashes + A Hash function produces a fixed length output (called hash value or message + digest) from a variable length message input. + + Implemented hash functions: + - MD5 (md5.h) + - SHA-1 (sha1.h) + - SHA-256 (sha256.h) + + \subsection MACs Message-Authentification-Codes (MACs) + - HMAC-SHA-1 (hmac-sha1.h) + - HMAC-SHA-256 (hmac-sha256.h) + + \subsection PRNGs Pseudo-Random-Number-Generators (PRNGs) + - Entropium (entropium.h) + +*/ \ No newline at end of file -- 2.39.5