From 9b1bf59ca8d49db1a7495d95119c68d62b036c59 Mon Sep 17 00:00:00 2001 From: bg Date: Sun, 8 Oct 2006 14:02:29 +0000 Subject: [PATCH] documentation upgrade; most docu still missing but a first step is done --- Doxyfile | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 2 + cast5.c | 37 +++++-- main.c | 2 +- md5.c | 11 ++- prng.c | 70 +++++++++---- sha256-asm.h | 9 +- sha256.c | 52 ++++++++-- sha256.h | 14 ++- xtea.c | 9 +- 10 files changed, 427 insertions(+), 54 deletions(-) create mode 100644 Doxyfile diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..2d42cc6 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,275 @@ +# Doxyfile 1.4.7 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = micro-crypt +PROJECT_NUMBER = 0.001 +OUTPUT_DIRECTORY = /home/bg/workspace/micro-crypt/doc/ +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +USE_WINDOWS_ENCODING = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = /home/bg/workspace/micro-crypt/ +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = /home/bg/workspace/micro-crypt +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py \ + *.C \ + *.CC \ + *.C++ \ + *.II \ + *.I++ \ + *.H \ + *.HH \ + *.H++ \ + *.CS \ + *.PHP \ + *.PHP3 \ + *.M \ + *.MM \ + *.PY +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = YES +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 1024 +MAX_DOT_GRAPH_HEIGHT = 1024 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/Makefile b/Makefile index 66043fa..b207adb 100644 --- a/Makefile +++ b/Makefile @@ -29,6 +29,8 @@ all: $(PRG).elf lst text eeprom $(PRG).elf: $(OBJ) $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ $(LIBS) +#rc6-test: + clean: rm -rf *.o $(PRG).elf *.eps *.png *.pdf *.bak rm -rf *.lst *.map $(EXTRA_CLEAN_FILES) diff --git a/cast5.c b/cast5.c index ebe1ce6..34c5a78 100644 --- a/cast5.c +++ b/cast5.c @@ -1,22 +1,25 @@ /* - * File: cast5.c - * Author: Daniel Otte - * Date: 26.07.2006 - * License: GPL - * Description: Implementation of the CAST5 (aka CAST-128) cipher algorithm as described in RFC 2144 + * \file cast5.c + * \author Daniel Otte + * \date 26.07.2006 + * \par License: + * GPL + * \brief Implementation of the CAST5 (aka CAST-128) cipher algorithm as described in RFC 2144 * */ - //pgm_read_dword #include #include #include "cast5.h" #include "config.h" - #include "uart.h" #include "debug.h" #undef DEBUG + #ifdef DEBUG + #include "uart.h" + #endif + #include "cast5-sbox.h" @@ -85,7 +88,12 @@ 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(cast5_ctx_t* s, uint8_t* key, uint8_t keylength){ /* we migth return if the key is valid and if setup was sucessfull */ uint32_t x[4], z[4]; @@ -237,8 +245,13 @@ uint32_t cast5_f3(uint32_t d, uint32_t m, uint8_t r){ #endif } +/*************************************************************************/ - +/** + * \brief encrypts a datablock with cast5 + * @param s Pointer to cast5 roundkeys (context) + * @param block Pointer to datablock + */ void cast5_enc(cast5_ctx_t *s, void* block){ uint32_t l,r, x, y; uint8_t i; @@ -261,7 +274,13 @@ void cast5_enc(cast5_ctx_t *s, void* block){ ((uint32_t*)block)[1]=l; } +/*************************************************************************/ +/** + * \brief decrypts a datablock with cast5 + * @param s Pointer to cast5 roundkeys (context) + * @param block Pointer to datablock + */ void cast5_dec(cast5_ctx_t *s, void* block){ uint32_t l,r, x, y; int8_t i, rounds; diff --git a/main.c b/main.c index 532e846..81dae92 100644 --- a/main.c +++ b/main.c @@ -34,7 +34,7 @@ #include "uart.h" #include "debug.h" -#include "sha256-asm.h" +#include "sha256.h" #include "xtea.h" #include "arcfour.h" #include "prng.h" diff --git a/md5.c b/md5.c index 5ae22e6..3c520ed 100644 --- a/md5.c +++ b/md5.c @@ -1,9 +1,10 @@ /* - * File: md5.h - * Author: Daniel Otte - * Date: 31.07.2006 - * License: GPL - * Description: Implementation of the MD5 hash algorithm as described in RFC 1321 + * \file md5.c + * \author Daniel Otte + * \date 31.07.2006 + * \par License: + * GPL + * \brief Implementation of the MD5 hash algorithm as described in RFC 1321 * */ diff --git a/prng.c b/prng.c index 640c2ac..078ed0d 100644 --- a/prng.c +++ b/prng.c @@ -1,16 +1,34 @@ /** - * File: prng.c - * Author: Daniel Otte - * Date: 17.05.2006 - * License: GPL - * Description: This file contains an implementaition of a pseudo-random-number generator. + * \file prng.c + * \author Daniel Otte + * \date 17.05.2006 + * \par License: + * GPL + * \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) | # + * +---------------+ # o---------o (xor)+---------+ o---------o o---------o # +--------------+ + * | entropy Block | -----> | sha-256 | --(offset)-< | rndCore | ---> | sha-256 | --+-> | sha-256 | -----> | random Block | + * +---------------+ # o---------o (xor)+---------+ o---------o | o---------o # +--------------+ + * # (xor) (xor) | # + * # ^ ^ | # + * # \ / | # + * # (offset)---------------------+ # + * # # + * #################################################################################### + * \endverbatim + */ -/* - * + /* \verbatim * #################################################################################### * # # * # +---------------------------+ # @@ -26,20 +44,28 @@ * # (offset)---------------------+ # * # # * #################################################################################### - * + * \endverbatim */ #include #include #include "sha256.h" +/** + * \brief secret entropy pool. + * This is the core of the random which is generated + */ +uint32_t rndCore[16]; +/*************************************************************************/ - -uint32_t rndCore[16]; /* secret */ - -/* - * idea is: hash the message and add it via xor to rndCore +/** + * \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 * @@ -62,7 +88,12 @@ void addEntropy(unsigned length, void* data){ } offset ^= 8; /* hehe */ } - + +/*************************************************************************/ +/** + * \brief This function fills a given buffer with 32 random bytes + * @param b Pointer to buffer wich is to fill + */ void getRandomBlock(uint32_t *b){ sha256_ctx_t s; uint8_t offset=8; @@ -79,8 +110,13 @@ void getRandomBlock(uint32_t *b){ sha256_lastBlock(&s, b, 256); memcpy(b, s.h, 32); } + +/*************************************************************************/ -/* this does some simple buffering */ +/** + * \brief This function simply returns a random byte + * @return a random byte + */ uint8_t getRandomByte(void){ static uint8_t block[32]; static uint8_t i=32; diff --git a/sha256-asm.h b/sha256-asm.h index 65e4c22..c1f9bf4 100644 --- a/sha256-asm.h +++ b/sha256-asm.h @@ -1,8 +1,9 @@ /** - * File: sha256-asm.h - * Author: Daniel Otte - * Date: 16.05.2006 - * License: GPL + * \file sha256-asm.h + * \author Daniel Otte + * \date 16.05.2006 + * \par License + * GPL * */ diff --git a/sha256.c b/sha256.c index 524b1dd..fea9340 100644 --- a/sha256.c +++ b/sha256.c @@ -1,8 +1,13 @@ /** - * File: sha256.c - * Author: Daniel Otte - * Date: 16.05.2006 - * License: GPL + * \file sha256.c + * \author Daniel Otte + * \date 16.05.2006 + * + * \par License: + * GPL + * + * \brief SHA-256 implementation. + * * */ @@ -19,23 +24,38 @@ #endif +/*************************************************************************/ + uint32_t sha256_init_vector[]={ 0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A, 0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19 }; + +/*************************************************************************/ + +/** + * \brief \c sh256_init initialises a sha256 context for hashing. + * \c sh256_init c initialises the given sha256 context for hashing + * @param state pointer to a sha256 context + * @return none + */ void sha256_init(sha256_ctx_t *state){ state->length=0; memcpy(state->h, sha256_init_vector, 8*4); } -/* +/*************************************************************************/ + +/** * rotate x right by n positions */ - uint32_t rotr32( uint32_t x, uint8_t n){ return ((x>>n) | (x<<(32-n))); } + +/*************************************************************************/ + // #define CHANGE_ENDIAN32(x) (((x)<<24) | ((x)>>24) | (((x)& 0x0000ff00)<<8) | (((x)& 0x00ff0000)>>8)) uint32_t change_endian32(uint32_t x){ @@ -43,6 +63,8 @@ uint32_t change_endian32(uint32_t x){ } +/*************************************************************************/ + /* sha256 functions as macros for speed and size, cause they are called only once */ #define CH(x,y,z) (((x)&(y)) ^ ((~(x))&(z))) @@ -66,6 +88,8 @@ uint32_t k[]={ }; +/*************************************************************************/ + /** * block must be, 512, Bit = 64, Byte, long !!! */ @@ -105,11 +129,17 @@ void sha256_nextBlock (sha256_ctx_t *state, void* block){ state->length += 512; } -/* - * length is the length of only THIS block in BITS not in bytes! + +/*************************************************************************/ + +/** + * \brief function to process the last block being hashed + * @param state Pointer to the context in which this block should be processed. + * @param block Pointer to the message wich should be hashed. + * @param length is the length of only THIS block in BITS not in bytes! * bits are big endian, meaning high bits come first. * if you have a message with bits at the end, the byte must be padded with zeros - * */ + */ void sha256_lastBlock(sha256_ctx_t *state, void* block, uint16_t length){ uint8_t lb[SHA256_BLOCK_BITS/8]; /* local block */ state->length += length; @@ -145,10 +175,11 @@ void sha256_lastBlock(sha256_ctx_t *state, void* block, uint16_t length){ } +/*************************************************************************/ + /* * length in bits! */ - void sha256(sha256_hash_t *dest, void* msg, uint32_t length){ /* length could be choosen longer but this is for ?C */ sha256_ctx_t s; sha256_init(&s); @@ -163,6 +194,7 @@ void sha256(sha256_hash_t *dest, void* msg, uint32_t length){ /* length could be +/*************************************************************************/ void sha256_ctx2hash(sha256_hash_t *dest, sha256_ctx_t *state){ #if defined LITTLE_ENDIAN diff --git a/sha256.h b/sha256.h index 80970ff..7dc9eeb 100644 --- a/sha256.h +++ b/sha256.h @@ -1,8 +1,9 @@ /** - * File: sha256.h - * Author: Daniel Otte - * Date: 16.05.2006 - * License: GPL + * \file sha256-asm.h + * \author Daniel Otte + * \date 16.05.2006 + * \par License + * GPL * */ @@ -18,6 +19,10 @@ #define SHA256_HASH_BITS 256 #define SHA256_BLOCK_BITS 512 +/** + * \brief sha256 context type + * + */ typedef struct { uint32_t h[8]; uint64_t length; @@ -26,6 +31,7 @@ typedef struct { typedef uint8_t sha256_hash_t[SHA256_HASH_BITS/8]; void sha256_init(sha256_ctx_t *state); + void sha256_nextBlock (sha256_ctx_t *state, void* block); void sha256_lastBlock(sha256_ctx_t *state, void* block, uint16_t length); diff --git a/xtea.c b/xtea.c index c9fe103..70ad914 100644 --- a/xtea.c +++ b/xtea.c @@ -1,8 +1,9 @@ -/* - * XTEA implemantation - * copy'n'pasted from http://en.wikipedia.org/wiki/XTEA +/** + * \file xtea.c + * \brief XTEA implemantation + * copy'n'pasted from http://en.wikipedia.org/wiki/XTEA * and slightly modified - * */ + */ #include -- 2.39.5