include/beecrypt/beecrypt.h

Go to the documentation of this file.

/*
 * Copyright (c) 1999, 2000, 2001, 2002 X-Way Rights BV
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

#ifndef _BEECRYPT_H
#define _BEECRYPT_H

#include "beecrypt/api.h"

#include "beecrypt/memchunk.h"
#include "beecrypt/mpnumber.h"

/*
 * Entropy Sources
 */

typedef int (*entropyNext)(byte*, size_t);

#ifdef __cplusplus
struct BEECRYPTAPI entropySource
#else
struct _entropySource
#endif
{
    const char*         name;
    const entropyNext   next;
};

#ifndef __cplusplus
typedef struct _entropySource entropySource;
#endif

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int                     entropySourceCount(void);

BEECRYPTAPI
const entropySource*    entropySourceGet(int n);

BEECRYPTAPI
const entropySource*    entropySourceFind(const char* name);

BEECRYPTAPI
const entropySource*    entropySourceDefault(void);

BEECRYPTAPI
int                     entropyGatherNext(byte*, size_t);

#ifdef __cplusplus
}
#endif

/*
 * Pseudo-random Number Generators
 */

typedef void randomGeneratorParam;

typedef int (*randomGeneratorSetup  )(randomGeneratorParam*);
typedef int (*randomGeneratorSeed   )(randomGeneratorParam*, const byte*, size_t);
typedef int (*randomGeneratorNext   )(randomGeneratorParam*, byte*, size_t);
typedef int (*randomGeneratorCleanup)(randomGeneratorParam*);

/*
 * The struct 'randomGenerator' holds information and pointers to code specific
 * to each random generator. Each specific random generator MUST be written to
 * be multithread safe.
 *
 * WARNING: each randomGenerator, when used in cryptographic applications, MUST
 * be guaranteed to be of suitable quality and strength (i.e. don't use the
 * random() function found in most UN*X-es).
 *
 * Multiple instances of each randomGenerator can be used (even concurrently),
 * provided they each use their own randomGeneratorParam parameters, a chunk
 * of memory which must be at least as large as indicated by the paramsize
 * field.
 *
 */

#ifdef __cplusplus
struct BEECRYPTAPI randomGenerator
#else
struct _randomGenerator
#endif
{
    const char*                     name;
    const size_t                    paramsize;
    const randomGeneratorSetup      setup;
    const randomGeneratorSeed       seed;
    const randomGeneratorNext       next;
    const randomGeneratorCleanup    cleanup;
};

#ifndef __cplusplus
typedef struct _randomGenerator randomGenerator;
#endif

/*
 * You can use the following functions to find random generators implemented by
 * the library:
 *
 * randomGeneratorCount returns the number of generators available.
 *
 * randomGeneratorGet returns the random generator with a given index (starting
 * at zero, up to randomGeneratorCount() - 1), or NULL if the index was out of
 * bounds.
 *
 * randomGeneratorFind returns the random generator with the given name, or
 * NULL if no random generator exists with that name.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int                     randomGeneratorCount(void);
BEECRYPTAPI
const randomGenerator*  randomGeneratorGet(int);
BEECRYPTAPI
const randomGenerator*  randomGeneratorFind(const char*);
BEECRYPTAPI
const randomGenerator*  randomGeneratorDefault(void);

#ifdef __cplusplus
}
#endif

/*
 * The struct 'randomGeneratorContext' is used to contain both the functional
 * part (the randomGenerator), and its parameters.
 */

#ifdef __cplusplus
struct BEECRYPTAPI randomGeneratorContext
#else
struct _randomGeneratorContext
#endif
{
    const randomGenerator* rng;
    randomGeneratorParam* param;

    #ifdef __cplusplus
    randomGeneratorContext();
    randomGeneratorContext(const randomGenerator*);
    ~randomGeneratorContext();
    #endif
};

#ifndef __cplusplus
typedef struct _randomGeneratorContext randomGeneratorContext;
#endif

/*
 * The following functions can be used to initialize and free a
 * randomGeneratorContext. Initializing will allocate a buffer of the size
 * required by the randomGenerator, freeing will deallocate that buffer.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int randomGeneratorContextInit(randomGeneratorContext*, const randomGenerator*);
BEECRYPTAPI
int randomGeneratorContextFree(randomGeneratorContext*);
BEECRYPTAPI
int randomGeneratorContextNext(randomGeneratorContext*, byte*, size_t);
BEECRYPTAPI
int randomGeneratorContextSeed(randomGeneratorContext*, const byte*, size_t);

#ifdef __cplusplus
}
#endif

/*
 * Hash Functions
 */

typedef void hashFunctionParam;

typedef int (*hashFunctionReset )(hashFunctionParam*);
typedef int (*hashFunctionUpdate)(hashFunctionParam*, const byte*, size_t);
typedef int (*hashFunctionDigest)(hashFunctionParam*, byte*);

/*
 * The struct 'hashFunction' holds information and pointers to code specific
 * to each hash function. Specific hash functions MAY be written to be
 * multithread-safe.
 *
 * NOTE: data MUST have a size (in bytes) of at least 'digestsize' as described
 * in the hashFunction struct.
 * NOTE: for safety reasons, after calling digest, each specific implementation
 * MUST reset itself so that previous values in the parameters are erased.
 */
#ifdef __cplusplus
struct BEECRYPTAPI hashFunction
#else
struct _hashFunction
#endif
{
    const char*                 name;
    const size_t                paramsize;  /* in bytes */
    const size_t                blocksize;  /* in bytes */
    const size_t                digestsize; /* in bytes */
    const hashFunctionReset     reset;
    const hashFunctionUpdate    update;
    const hashFunctionDigest    digest;
};

#ifndef __cplusplus
typedef struct _hashFunction hashFunction;
#endif

/*
 * You can use the following functions to find hash functions implemented by
 * the library:
 *
 * hashFunctionCount returns the number of hash functions available.
 *
 * hashFunctionGet returns the hash function with a given index (starting
 * at zero, up to hashFunctionCount() - 1), or NULL if the index was out of
 * bounds.
 *
 * hashFunctionFind returns the hash function with the given name, or
 * NULL if no hash function exists with that name.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int                 hashFunctionCount(void);
BEECRYPTAPI
const hashFunction* hashFunctionGet(int);
BEECRYPTAPI
const hashFunction* hashFunctionFind(const char*);
BEECRYPTAPI
const hashFunction* hashFunctionDefault(void);

#ifdef __cplusplus
}
#endif

/*
 * The struct 'hashFunctionContext' is used to contain both the functional
 * part (the hashFunction), and its parameters.
 */
#ifdef __cplusplus
struct BEECRYPTAPI hashFunctionContext
#else
struct _hashFunctionContext
#endif
{
    const hashFunction* algo;
    hashFunctionParam* param;

    #ifdef __cplusplus
    hashFunctionContext();
    hashFunctionContext(const hashFunction*);
    ~hashFunctionContext();
    #endif
};

#ifndef __cplusplus
typedef struct _hashFunctionContext hashFunctionContext;
#endif

/*
 * The following functions can be used to initialize and free a
 * hashFunctionContext. Initializing will allocate a buffer of the size
 * required by the hashFunction, freeing will deallocate that buffer.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int hashFunctionContextInit(hashFunctionContext*, const hashFunction*);
BEECRYPTAPI
int hashFunctionContextFree(hashFunctionContext*);
BEECRYPTAPI
int hashFunctionContextReset(hashFunctionContext*);
BEECRYPTAPI
int hashFunctionContextUpdate(hashFunctionContext*, const byte*, size_t);
BEECRYPTAPI
int hashFunctionContextUpdateMC(hashFunctionContext*, const memchunk*);
BEECRYPTAPI
int hashFunctionContextUpdateMP(hashFunctionContext*, const mpnumber*);
BEECRYPTAPI
int hashFunctionContextDigest(hashFunctionContext*, byte*);
BEECRYPTAPI
int hashFunctionContextDigestMP(hashFunctionContext*, mpnumber*);
BEECRYPTAPI
int hashFunctionContextDigestMatch(hashFunctionContext*, const mpnumber*);

#ifdef __cplusplus
}
#endif

/*
 * Keyed Hash Functions, a.k.a. Message Authentication Codes
 */

typedef void keyedHashFunctionParam;

typedef int (*keyedHashFunctionSetup  )(keyedHashFunctionParam*, const byte*, size_t);
typedef int (*keyedHashFunctionReset  )(keyedHashFunctionParam*);
typedef int (*keyedHashFunctionUpdate )(keyedHashFunctionParam*, const byte*, size_t);
typedef int (*keyedHashFunctionDigest )(keyedHashFunctionParam*, byte*);

/*
 * The struct 'keyedHashFunction' holds information and pointers to code
 * specific to each keyed hash function. Specific keyed hash functions MAY be
 * written to be multithread-safe.
 *
 * The struct field 'keybitsmin' contains the minimum number of bits a key
 * must contains, 'keybitsmax' the maximum number of bits a key may contain,
 * 'keybitsinc', the increment in bits that may be used between min and max.
 * 
 * NOTE: data must be at least have a bytesize of 'digestsize' as described
 * in the keyedHashFunction struct.
 * NOTE: for safety reasons, after calling digest, each specific implementation
 * MUST reset itself so that previous values in the parameters are erased.
 */
#ifdef __cplusplus
struct BEECRYPTAPI keyedHashFunction
#else
struct _keyedHashFunction
#endif
{
    const char*                     name;
    const size_t                    paramsize;  /* in bytes */
    const size_t                    blocksize;  /* in bytes */
    const size_t                    digestsize; /* in bytes */
    const size_t                    keybitsmin; /* in bits */
    const size_t                    keybitsmax; /* in bits */
    const size_t                    keybitsinc; /* in bits */
    const keyedHashFunctionSetup    setup;
    const keyedHashFunctionReset    reset;
    const keyedHashFunctionUpdate   update;
    const keyedHashFunctionDigest   digest;
};

#ifndef __cplusplus
typedef struct _keyedHashFunction keyedHashFunction;
#endif

/*
 * You can use the following functions to find keyed hash functions implemented
 * by the library:
 *
 * keyedHashFunctionCount returns the number of keyed hash functions available.
 *
 * keyedHashFunctionGet returns the keyed hash function with a given index
 * (starting at zero, up to keyedHashFunctionCount() - 1), or NULL if the index
 * was out of bounds.
 *
 * keyedHashFunctionFind returns the keyed hash function with the given name,
 * or NULL if no keyed hash function exists with that name.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int                         keyedHashFunctionCount(void);
BEECRYPTAPI
const keyedHashFunction*    keyedHashFunctionGet(int);
BEECRYPTAPI
const keyedHashFunction*    keyedHashFunctionFind(const char*);
BEECRYPTAPI
const keyedHashFunction*    keyedHashFunctionDefault(void);

#ifdef __cplusplus
}
#endif

/*
 * The struct 'keyedHashFunctionContext' is used to contain both the functional
 * part (the keyedHashFunction), and its parameters.
 */
#ifdef __cplusplus
struct BEECRYPTAPI keyedHashFunctionContext
#else
struct _keyedHashFunctionContext
#endif
{
    const keyedHashFunction*    algo;
    keyedHashFunctionParam*     param;

    #ifdef __cplusplus
    keyedHashFunctionContext();
    keyedHashFunctionContext(const keyedHashFunction*);
    ~keyedHashFunctionContext();
    #endif
};

#ifndef __cplusplus
typedef struct _keyedHashFunctionContext keyedHashFunctionContext;
#endif

/*
 * The following functions can be used to initialize and free a
 * keyedHashFunctionContext. Initializing will allocate a buffer of the size
 * required by the keyedHashFunction, freeing will deallocate that buffer.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int keyedHashFunctionContextInit(keyedHashFunctionContext*, const keyedHashFunction*);
BEECRYPTAPI
int keyedHashFunctionContextFree(keyedHashFunctionContext*);
BEECRYPTAPI
int keyedHashFunctionContextSetup(keyedHashFunctionContext*, const byte*, size_t);
BEECRYPTAPI
int keyedHashFunctionContextReset(keyedHashFunctionContext*);
BEECRYPTAPI
int keyedHashFunctionContextUpdate(keyedHashFunctionContext*, const byte*, size_t);
BEECRYPTAPI
int keyedHashFunctionContextUpdateMC(keyedHashFunctionContext*, const memchunk*);
BEECRYPTAPI
int keyedHashFunctionContextUpdateMP(keyedHashFunctionContext*, const mpnumber*);
BEECRYPTAPI
int keyedHashFunctionContextDigest(keyedHashFunctionContext*, byte*);
BEECRYPTAPI
int keyedHashFunctionContextDigestMP(keyedHashFunctionContext*, mpnumber*);
BEECRYPTAPI
int keyedHashFunctionContextDigestMatch(keyedHashFunctionContext*, const mpnumber*);

#ifdef __cplusplus
}
#endif

/*
 * Block ciphers
 */

typedef enum
{
    NOCRYPT,
    ENCRYPT,
    DECRYPT
} cipherOperation;

typedef void blockCipherParam;

typedef int (*blockCipherSetup  )(blockCipherParam*, const byte*, size_t, cipherOperation);

typedef int (*blockCipherSetIV  )(blockCipherParam*, const byte*);

typedef int (*blockCipherSetCTR )(blockCipherParam*, const byte*, size_t);


typedef int (*blockCipherRawcrypt)(blockCipherParam*, uint32_t*, const uint32_t*);

typedef int (*blockCipherModcrypt)(blockCipherParam*, uint32_t*, const uint32_t*, unsigned int);

typedef uint32_t* (*blockCipherFeedback)(blockCipherParam*);

typedef struct
{
    const blockCipherRawcrypt encrypt;
    const blockCipherRawcrypt decrypt;
} blockCipherRaw;

typedef struct
{
    const blockCipherModcrypt encrypt;
    const blockCipherModcrypt decrypt;
} blockCipherMode;

#ifdef __cplusplus
struct BEECRYPTAPI blockCipher
#else
struct _blockCipher
#endif
{
    const char*                 name;
    const size_t                paramsize;
    const size_t                blocksize;
    const size_t                keybitsmin;
    const size_t                keybitsmax;
    const size_t                keybitsinc;
    const blockCipherSetup      setup;
    const blockCipherSetIV      setiv;
    const blockCipherSetCTR     setctr;
    const blockCipherFeedback   getfb;
    const blockCipherRaw        raw;
    const blockCipherMode       ecb;
    const blockCipherMode       cbc;
    const blockCipherMode       ctr;
};

#ifndef __cplusplus
typedef struct _blockCipher blockCipher;
#endif

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int                     blockCipherCount(void);

BEECRYPTAPI
const blockCipher*      blockCipherGet(int);

BEECRYPTAPI
const blockCipher*      blockCipherFind(const char*);

BEECRYPTAPI
const blockCipher*      blockCipherDefault(void);

#ifdef __cplusplus
}
#endif

#ifdef __cplusplus
struct BEECRYPTAPI blockCipherContext
#else
struct _blockCipherContext
#endif
{
    const blockCipher*  algo;
    blockCipherParam*   param;
    cipherOperation     op;

    #ifdef __cplusplus
    blockCipherContext();
    blockCipherContext(const blockCipher*);
    ~blockCipherContext();
    #endif
};

#ifndef __cplusplus
typedef struct _blockCipherContext blockCipherContext;
#endif

/*
 * The following functions can be used to initialize and free a
 * blockCipherContext. Initializing will allocate a buffer of the size
 * required by the blockCipher, freeing will deallocate that buffer.
 */

#ifdef __cplusplus
extern "C" {
#endif

BEECRYPTAPI
int blockCipherContextInit(blockCipherContext*, const blockCipher*);

BEECRYPTAPI
int blockCipherContextSetup(blockCipherContext*, const byte*, size_t, cipherOperation);

BEECRYPTAPI
int blockCipherContextSetIV(blockCipherContext*, const byte*);

BEECRYPTAPI
int blockCipherContextSetCTR(blockCipherContext*, const byte*, size_t);

BEECRYPTAPI
int blockCipherContextFree(blockCipherContext*);

BEECRYPTAPI
int blockCipherContextECB(blockCipherContext*, uint32_t*, const uint32_t*, int);

BEECRYPTAPI
int blockCipherContextCBC(blockCipherContext*, uint32_t*, const uint32_t*, int);

BEECRYPTAPI
int blockCipherContextCTR(blockCipherContext*, uint32_t*, const uint32_t*, int);

BEECRYPTAPI
int blockCipherContextValidKeylen(blockCipherContext*, size_t);

#ifdef __cplusplus
}
#endif

#endif

---