path: root/beecrypt/beecrypt.h

/*
 * Copyright (c) 1999, 2000, 2001, 2002 Virtual Unlimited B.V.
 *
 * 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
 *
 */

/*!\file beecrypt.h
 * \brief BeeCrypt API, headers.
 *
 * These API functions provide an abstract way for using most of
 * the various algorithms implemented by the library.
 *
 * \author Bob Deblier <bob.deblier@pandora.be>
 * \ingroup ES_m PRNG_m HASH_m HMAC_m BC_m
 */

#ifndef _BEECRYPT_H
#define _BEECRYPT_H

#include "beecrypt.api.h"

#include "memchunk.h"
#include "mpnumber.h"
#include "mp.h"

/** \name Entropy sources */
/*@{*/

/** \ingroup ES_m
 * Return an array of 32-bit unsigned integers of given size with
 * entropy data.
 *
 * @retval data		entropy data
 * @param size		no. of ints of data
 * @return		0 on success, -1 on failure
 */
typedef int (*entropyNext) (/*@out@*/ byte* data, size_t size)
	/*@modifies data @*/;

/** \ingroup ES_m
 * Methods and parameters for entropy sources.
 * Each specific entropy source MUST be written to be multithread-safe.
 */
typedef struct
{
/*@observer@*/
    const char* name;		/*!< entropy source name */
/*@unused@*/
    const entropyNext next;	/*!< return entropy function */
} entropySource;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup ES_m
 * Return the number of entropy sources available.
 * @return		number of entropy sources available
 */
BEECRYPTAPI /*@unused@*/
int entropySourceCount(void)
	/*@*/;

/** \ingroup ES_m
 * Retrieve a entropy source by index.
 * @param n		entropy source index
 * @return		entropy source pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const entropySource* entropySourceGet(int n)
	/*@*/;

/** \ingroup ES_m
 * Retrieve a entropy source by name.
 * @param name		entropy source name
 * @return		entropy source pointer (or NULL)
 */
/*@-exportlocal@*/
BEECRYPTAPI /*@observer@*/ /*@null@*/
const entropySource* entropySourceFind(const char* name)
	/*@*/;
/*@=exportlocal@*/

/** \ingroup ES_m
 * Retrieve the default entropy source.
 * If the BEECRYPT_ENTROPY environment variable is set, use that
 * entropy source. Otherwise, use the 1st entry in the internal table.
 * @return		entropy source pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const entropySource* entropySourceDefault(void)
	/*@*/;

/** \ingroup ES_m
 * Gather entropy from multiple sources (if BEECRYPT_ENTROPY is not set).
 *
 * @retval data		entropy data
 * @param size		no. of ints of data
 * @return		0 on success, -1 on failure
 */
BEECRYPTAPI
int entropyGatherNext(byte* data, size_t size)
	/*@*/;

#ifdef __cplusplus
}
#endif

/*@}*/
/** \name Pseudo-random Number Generators */
/*@{*/

/** \ingroup PRNG_m
 */
typedef void randomGeneratorParam;

/** \ingroup PRNG_m
 * Initialize the parameters for use, and seed the generator
 * with entropy from the default entropy source.
 *
 * @param param		generator parameters
 * @return		0 on success, -1 on failure
 */
typedef int (*randomGeneratorSetup) (randomGeneratorParam* param)
	/*@modifies *param @*/;

/** \ingroup PRNG_m
 * Re-seed the random generator with user-provided entropy.
 *
 * @param param		generator parameters
 * @param data		user entropy
 * @param size		no. of ints of entropy
 * @return		0 on success, -1 on failure
 */
typedef int (*randomGeneratorSeed) (randomGeneratorParam* param, const byte* data, size_t size)
	/*@modifies *param @*/;

/** \ingroup PRNG_m
 * Return an array of 32-bit unsigned integers of given size with
 * pseudo-random data.
 *
 * @param param		generator parameters
 * @retval data		pseudo-random data
 * @param size		no. of ints of data
 * @return		0 on success, -1 on failure
 */
typedef int (*randomGeneratorNext) (randomGeneratorParam* param, /*@out@*/ byte* data, size_t size)
	/*@modifies *param, *data @*/;

/** \ingroup PRNG_m
 * Cleanup after using a generator.
 *
 * @param param		generator parameters
 * @return		0 on success, -1 on failure
 */
typedef int (*randomGeneratorCleanup) (randomGeneratorParam* param)
	/*@modifies *param @*/;

/** \ingroup PRNG_m
 * Methods and parameters for random generators.
 * 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.
 *
 */
typedef struct
{
/*@observer@*/
    const char* name;			/*!< random generator name */
    const size_t paramsize;
    const randomGeneratorSetup setup;
    const randomGeneratorSeed seed;
    const randomGeneratorNext next;
    const randomGeneratorCleanup cleanup;
} randomGenerator;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup PRNG_m
 * Return the number of generators available.
 * @return		number of generators available
 */
BEECRYPTAPI /*@unused@*/
int randomGeneratorCount(void)
	/*@*/;

/** \ingroup PRNG_m
 * Retrieve a generator by index.
 * @param index		generator index
 * @return		generator pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const randomGenerator* randomGeneratorGet(int index)
	/*@*/;

/** \ingroup PRNG_m
 * Retrieve a generator by name.
 * @param name		generator name
 * @return		generator pointer (or NULL)
 */
/*@-exportlocal@*/
BEECRYPTAPI /*@observer@*/ /*@null@*/
const randomGenerator* randomGeneratorFind(const char* name)
	/*@*/;
/*@=exportlocal@*/

/** \ingroup PRNG_m
 * Retrieve the default generator.
 * If the BEECRYPT_RANDOM environment variable is set, use that
 * generator. Otherwise, use "fips186prng".
 * @return		generator pointer
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const randomGenerator* randomGeneratorDefault(void)
	/*@*/;

#ifdef __cplusplus
}
#endif

/** \ingroup PRNG_m
 * A randomGenerator instance, global functions and specific parameters.
 */
typedef struct
{
/*@observer@*/ /*@dependent@*/
    const randomGenerator* rng;		/*!< global functions and parameters */
/*@only@*/
    randomGeneratorParam* param;	/*!< specific parameters */
} randomGeneratorContext;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup PRNG_m
 * Initialize a randomGenerator instance.
 */
BEECRYPTAPI /*@unused@*/
int randomGeneratorContextInit(/*@special@*/ /*@null@*/ randomGeneratorContext* ctxt, /*@observer@*/ /*@dependent@*/ /*@null@*/ const randomGenerator* rng)
	/*@defines ctxt->rng, ctxt->param @*/
	/*@modifies ctxt->rng, ctxt->param @*/;

/** \ingroup PRNG_m
 * Destroy a randomGenerator instance.
 */
BEECRYPTAPI /*@unused@*/
int randomGeneratorContextFree(/*@special@*/ randomGeneratorContext* ctxt)
	/*@uses ctxt->rng @*/
	/*@releases ctxt->param @*/
	/*@modifies ctxt->rng, ctxt->param @*/;

BEECRYPTAPI /*@unused@*/
int randomGeneratorContextNext(randomGeneratorContext* ctxt, /*@out@*/ byte* data, size_t size)
	/*@modifies ctxt->param, *data @*/;

#ifdef __cplusplus
}
#endif

/*@}*/
/** \name Hash Functions */
/*@{*/

/** \ingroup HASH_m
 */
BEECRYPTAPI
typedef void hashFunctionParam;

/** \ingroup HASH_m
 * Re-initialize the parameters of the hash function.
 *
 * @param param		hash parameters
 * @return		0 on success, -1 on failure
 */
typedef int (*hashFunctionReset) (hashFunctionParam* param)
	/*@modifies *param @*/;

/** \ingroup HASH_m
 * Update the hash function with an array of bytes.
 *
 * @param param		hash parameters
 * @param data		array of bytes
 * @param size		no. of bytes
 * @return		0 on success, -1 on failure
 */
typedef int (*hashFunctionUpdate) (hashFunctionParam* param, const byte* data, size_t size)
	/*@modifies *param @*/;

/** \ingroup HASH_m
 * Compute the digest of all the data passed to the hash function, and return
 * the result in data.
 *
 * @note data must be at least have a bytesize of '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.
 *
 * @param param		hash parameters
 * @retval data		digest
 * @return		0 on success, -1 on failure
 */
typedef int (*hashFunctionDigest) (hashFunctionParam* param, /*@out@*/ byte* data)
	/*@modifies *param, *data @*/;

/** \ingroup HASH_m
 * Methods and parameters for hash functions.
 * Specific hash functions MAY be written to be multithread-safe.
 */
typedef struct
{
/*@observer@*/
    const char* name;			/*!< hash function 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;
} hashFunction;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup HASH_m
 * Return the number of hash functions available.
 * @return		number of hash functions available
 */
BEECRYPTAPI /*@unused@*/
int hashFunctionCount(void)
	/*@*/;

/** \ingroup HASH_m
 * Retrieve a hash function by index.
 * @param index		hash function index
 * @return		hash function pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const hashFunction* hashFunctionGet(int index)
	/*@*/;

/** \ingroup HASH_m
 * Retrieve a hash function by name.
 * @param name		hash function name
 * @return		hash function pointer (or NULL)
 */
/*@-exportlocal@*/
BEECRYPTAPI /*@observer@*/ /*@null@*/
const hashFunction* hashFunctionFind(const char* name)
	/*@*/;
/*@=exportlocal@*/

/** \ingroup HASH_m
 * Retrieve the default hash function.
 * If the BEECRYPT_HASH environment variable is set, use that
 * hash function. Otherwise, use "sha1".
 * @return		hash function pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const hashFunction* hashFunctionDefault(void)
	/*@*/;

#ifdef __cplusplus
}
#endif

/** \ingroup HASH_m
 * A hashFunction instance, global functions and specific parameters.
 */
typedef struct
{
/*@observer@*/ /*@dependent@*/
    const hashFunction* algo;	/*!< global functions and parameters */
/*@only@*/
    hashFunctionParam* param;	/*!< specific parameters */
} hashFunctionContext;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup HASH_m
 * Initialize a hashFunction instance.
 */
BEECRYPTAPI
int hashFunctionContextInit(/*@special@*/ hashFunctionContext* ctxt, /*@observer@*/ /*@dependent@*/ const hashFunction* hash)
	/*@defines ctxt->algo, ctxt->param @*/
	/*@modifies ctxt->algo, ctxt->param @*/;

/** \ingroup HASH_m
 * Destroy a hashFunction instance.
 */
BEECRYPTAPI
int hashFunctionContextFree(/*@special@*/ hashFunctionContext* ctxt)
	/*@releases ctxt->param @*/
	/*@modifies ctxt->algo, ctxt->param @*/;

/** \ingroup HASH_m
 */
BEECRYPTAPI
int hashFunctionContextReset(hashFunctionContext* ctxt)
	/*@modifies ctxt @*/;

/** \ingroup HASH_m
 */
BEECRYPTAPI /*@unused@*/
int hashFunctionContextUpdate(hashFunctionContext* ctxt, const byte* data, size_t size)
	/*@modifies ctxt @*/;

/** \ingroup HASH_m
 */
BEECRYPTAPI /*@unused@*/
int hashFunctionContextUpdateMC(hashFunctionContext* ctxt, const memchunk* m)
	/*@modifies ctxt @*/;

/** \ingroup HASH_m
 */
BEECRYPTAPI
int hashFunctionContextUpdateMP(hashFunctionContext* ctxt, const mpnumber* n)
	/*@modifies ctxt @*/;

/** \ingroup HASH_m
 */
BEECRYPTAPI
int hashFunctionContextDigest(hashFunctionContext* ctxt, byte* digest)
	/*@modifies ctxt, *digest @*/;

/** \ingroup HASH_m
 */
/*@-exportlocal@*/
BEECRYPTAPI
int hashFunctionContextDigestMP(hashFunctionContext* ctxt, mpnumber* d)
	/*@modifies ctxt, *d @*/;
/*@=exportlocal@*/

/** \ingroup HASH_m
 */
BEECRYPTAPI /*@unused@*/
int hashFunctionContextDigestMatch(hashFunctionContext* ctxt, const mpnumber* d)
	/*@modifies ctxt @*/;

#ifdef __cplusplus
}
#endif

/*@}*/
/** \name Keyed Hash Functions, a.k.a. Message Authentication Codes */
/*@{*/

/** \ingroup HMAC_m
 */
typedef void keyedHashFunctionParam;

/** \ingroup HMAC_m
 * Setup the keyed hash function parameters with the given secret key.
 * This can also be used to reset the parameters.
 *
 * @note After use, it is recommended to wipe the parameters by calling setup
 * again with another (dummy) key.
 *
 * @param param		keyed hash parameters
 * @param key		secret key
 * @param keybits	no. bits in secret key
 * @return		0 on success, -1 on failure
 */
typedef int (*keyedHashFunctionSetup) (keyedHashFunctionParam* param, const byte* key, size_t keybits)
	/*@modifies *param @*/;

/** \ingroup HMAC_m
 * Re-initialize the parameters of a keyed hash function.
 *
 * @param param		keyed hash parameters
 * @return		0 on success, -1 on failure
 */
typedef int (*keyedHashFunctionReset) (keyedHashFunctionParam* param)
	/*@modifies *param @*/;

/** \ingroup HMAC_m
 * Update the keyed hash function with an array of bytes.
 *
 * @param param		keyed hash parameters
 * @param data		array of bytes
 * @param size		no. of bytes
 * @return		0 on success, -1 on failure
 */
typedef int (*keyedHashFunctionUpdate) (keyedHashFunctionParam* param, const byte* data, size_t size)
	/*@modifies *param @*/;

/** \ingroup HMAC_m
 * Compute the digest (or authentication code) of all the data passed to
 * the keyed hash function, and return the result in data.
 *
 * @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.
 *
 * @param param		keyed hash parameters
 * @retval data		digest (or authentication code)
 * @return		0 on success, -1 on failure
 */
typedef int (*keyedHashFunctionDigest) (keyedHashFunctionParam* param, /*@out@*/ byte* data)
	/*@modifies *param, *data @*/;

/** \ingroup HMAC_m
 * Methods and parameters for keyed hash functions.
 * Specific keyed hash functions MAY be written to be multithread-safe.
 */
typedef struct
{
/*@observer@*/
    const char* name;			/*!< keyed hash function name */
    const size_t paramsize;		/*!< in bytes */
    const size_t blocksize;		/*!< in bytes */
    const size_t digestsize;		/*!< in bytes */
    const size_t keybitsmin;		/*!< min keysize in bits */
    const size_t keybitsmax;		/*!< max keysize in bits */
    const size_t keybitsinc;		/*!< keysize increment in bits */
    const keyedHashFunctionSetup setup;
    const keyedHashFunctionReset reset;
    const keyedHashFunctionUpdate update;
    const keyedHashFunctionDigest digest;
} keyedHashFunction;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup HMAC_m
 * Return the number of keyed hash functions available.
 * @return		number of keyed hash functions available
 */
BEECRYPTAPI /*@unused@*/
int keyedHashFunctionCount(void)
	/*@*/;

/** \ingroup HMAC_m
 * Retrieve a keyed hash function by index.
 * @param index		keyed hash function index
 * @return		keyed hash function pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const keyedHashFunction* keyedHashFunctionGet(int index)
	/*@*/;

/** \ingroup HMAC_m
 * Retrieve a keyed hash function by name.
 * @param name		keyed hash function name
 * @return		keyed hash function pointer (or NULL)
 */
/*@-exportlocal@*/
BEECRYPTAPI /*@observer@*/ /*@null@*/
const keyedHashFunction* keyedHashFunctionFind(const char* name)
	/*@*/;
/*@=exportlocal@*/

/** \ingroup HMAC_m
 * Retrieve the default keyed hash function.
 * If the BEECRYPT_KEYEDHASH environment variable is set, use that keyed
 * hash function. Otherwise, use "hmacsha1".
 * @return		keyed hash function pointer
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const keyedHashFunction* keyedHashFunctionDefault(void)
	/*@*/;

#ifdef __cplusplus
}
#endif

/** \ingroup HMAC_m
 * A keyedHashFunction instance, global functions and specific parameters.
 */
typedef struct
{
/*@observer@*/ /*@dependent@*/
    const keyedHashFunction* algo;	/*!< global functions and parameters */
/*@only@*/
    keyedHashFunctionParam* param;	/*!< specific parameters */
} keyedHashFunctionContext;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup HMAC_m
 * Initialize a keyedHashFunction instance.
 */
BEECRYPTAPI
int keyedHashFunctionContextInit(/*@special@*/ keyedHashFunctionContext* ctxt, /*@observer@*/ /*@dependent@*/ const keyedHashFunction* mac)
	/*@defines ctxt->algo, ctxt->param @*/
	/*@modifies ctxt->algo, ctxt->param @*/;

/** \ingroup HMAC_m
 * Destroy a keyedHashFunction instance.
 */
BEECRYPTAPI
int keyedHashFunctionContextFree(/*@special@*/ keyedHashFunctionContext* ctxt)
	/*@uses ctxt->algo @*/
	/*@releases ctxt->param @*/
	/*@modifies ctxt->algo, ctxt->param @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI
int keyedHashFunctionContextSetup(keyedHashFunctionContext* ctxt, const byte* key, size_t keybits)
	/*@modifies ctxt @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI /*@unused@*/
int keyedHashFunctionContextReset(keyedHashFunctionContext* ctxt)
	/*@modifies ctxt @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI /*@unused@*/
int keyedHashFunctionContextUpdate(keyedHashFunctionContext* ctxt, const byte* data, size_t size)
	/*@modifies ctxt @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI
int keyedHashFunctionContextUpdateMC(keyedHashFunctionContext* ctxt, const memchunk* m)
	/*@modifies ctxt @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI /*@unused@*/
int keyedHashFunctionContextUpdateMP(keyedHashFunctionContext* ctxt, const mpnumber* n)
	/*@modifies ctxt @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI /*@unused@*/
int keyedHashFunctionContextDigest(keyedHashFunctionContext* ctxt, byte* digest)
	/*@modifies ctxt, *digest @*/;

BEECRYPTAPI
int keyedHashFunctionContextDigestMP(keyedHashFunctionContext* ctxt, const mpnumber* d)
	/*@modifies ctxt, d @*/;

/** \ingroup HMAC_m
 */
BEECRYPTAPI
int keyedHashFunctionContextDigestMatch(keyedHashFunctionContext* ctxt, const mpnumber* d)
	/*@modifies ctxt @*/;

#ifdef __cplusplus
}
#endif

/*@}*/
/** \name Block ciphers */
/*@{*/

typedef void blockCipherParam;

/** \ingroup BC_m
 * Block cipher operations.
 */
typedef enum
{
	NOCRYPT,
	ENCRYPT,
	DECRYPT
} cipherOperation;

/** \ingroup BC_m
 * Setup the blockcipher parameters with the given secret key for either
 * encryption or decryption.
 *
 * @note After use, it is recommended to wipe the parameters by calling setup
 * again with another (dummy) key.
 *
 * @param param		blockcipher parameters
 * @param key		secret key
 * @param keybits	no. bits in secret key
 * @param cipherOperation
 * @return		0 on success, -1 on failure
 */
typedef int (*blockCipherSetup) (blockCipherParam* param, const byte* key, size_t keybits, cipherOperation cipherOperation)
	/*@modifies param @*/;

/** \ingroup BC_m
 * Initialize IV for blockcipher.
 * @param param		blockcipher parameters
 * @param data		iv data
 * @return		0 on success, -1 on failure
 */
typedef int (*blockCipherSetIV) (blockCipherParam* param, const byte* data)
	/*@modifies param @*/;

/** \ingroup BC_m
 * Encrypt/decrypt a block of data.
 * @note This is raw encryption, without padding, etc.
 *
 * @param param		blockcipher parameters
 * @retval dst		ciphertext block
 * @param src		plaintext block
 * @return		0 on success, -1 on failure
 */
typedef int (*blockCipherRawcrypt) (blockCipherParam* param, uint32_t* dst, const uint32_t* src)
	/*@modifies param, dst @*/;

/** \ingroup BC_m
 * Encrypt/decrypt multiple blocks of data.
 * @note This is raw decryption, without padding, etc.
 *
 * @param param		blockcipher parameters
 * @retval dst		plaintext block
 * @param src		ciphertext block
 * @param nblocks	no. of blocks
 * @return		0 on success, -1 on failure
 */
typedef int (*blockCipherModcrypt) (blockCipherParam* param, uint32_t* dst, const uint32_t* src, unsigned int nblocks)
	/*@modifies param, dst @*/;

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

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

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

/** \ingroup BC_m
 * Methods and parameters for block ciphers.
 * Specific block ciphers MAY be written to be multithread-safe.
 */
typedef struct
{
/*@observer@*/
    const char* name;			/*!< block cipher name */
    const size_t paramsize;		/*!< in bytes */
    const size_t blocksize;		/*!< in bytes */
    const size_t keybitsmin;		/*!< min keysize in bits */
    const size_t keybitsmax;		/*!< max keysize in bits */
    const size_t keybitsinc;		/*!< keysize increment in bits */
    const blockCipherSetup setup;
    const blockCipherSetIV setiv;
    const blockCipherRaw raw;
    const blockCipherMode ecb;
    const blockCipherMode cbc;
    const blockCipherFeedback getfb;
} blockCipher;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup BC_m
 * Return the number of blockciphers available.
 * @return		number of blockciphers available
 */
BEECRYPTAPI /*@unused@*/
int blockCipherCount(void)
	/*@*/;

/** \ingroup BC_m
 * Retrieve a blockcipher by index.
 * @param index		blockcipher index
 * @return		blockcipher pointer (or NULL)
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const blockCipher* blockCipherGet(int index)
	/*@*/;

/** \ingroup BC_m
 * Retrieve a blockcipher by name.
 * @param name		blockcipher name
 * @return		blockcipher pointer (or NULL)
 */
/*@-exportlocal@*/
BEECRYPTAPI /*@observer@*/ /*@null@*/
const blockCipher* blockCipherFind(const char* name)
	/*@*/;
/*@=exportlocal@*/

/** \ingroup BC_m
 * Retrieve the default blockcipher.
 * If the BEECRYPT_CIPHER environment variable is set, use that blockcipher.
 * Otherwise, use "blowfish".
 * @return		blockcipher pointer
 */
BEECRYPTAPI /*@observer@*/ /*@null@*/ /*@unused@*/
const blockCipher* blockCipherDefault(void)
	/*@*/;

#ifdef __cplusplus
}
#endif

/** \ingroup BC_m
 * A blockCipher instance, global functions and specific parameters.
 */
typedef struct
{
/*@observer@*/ /*@dependent@*/
    const blockCipher* algo;	/*!< global functions and parameters */
/*@only@*/
    blockCipherParam* param;	/*!< specific parameters */
    cipherOperation op;
} blockCipherContext;

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup BC_m
 * Initialize a blockCipher instance.
 */
BEECRYPTAPI
int blockCipherContextInit(/*@special@*/ blockCipherContext* ctxt, /*@observer@*/ /*@dependent@*/ const blockCipher* ciph)
	/*@defines ctxt->algo, ctxt->param, ctxt->op @*/
	/*@modifies ctxt->algo, ctxt->param, ctxt->op @*/;

/** \ingroup BC_m
 */
BEECRYPTAPI
int blockCipherContextSetup(blockCipherContext* ctxt, const byte* key, size_t keybits, cipherOperation op)
	/*@modifies ctxt @*/;

/** \ingroup BC_m
 */
BEECRYPTAPI /*@unused@*/
int blockCipherContextSetIV(blockCipherContext* ctxt, const byte* iv)
	/*@modifies ctxt @*/;

/** \ingroup BC_m
 * Destroy a blockCipher instance.
 */
BEECRYPTAPI
int blockCipherContextFree(/*@special@*/ blockCipherContext* ctxt)
	/*@releases ctxt->param @*/
	/*@modifies ctxt->algo, ctxt->param @*/;

/** \ingroup BC_m
 */
BEECRYPTAPI /*@unused@*/
int blockCipherContextECB(blockCipherContext* ctxt, uint32_t* dst, const uint32_t* src, size_t nblocks)
	/*@modifies ctxt->param, dst @*/;

/** \ingroup BC_m
 */
BEECRYPTAPI /*@unused@*/
int blockCipherContextCBC(blockCipherContext* ctxt, uint32_t* dst, const uint32_t* src, size_t nblocks)
	/*@modifies ctxt->param, dst @*/;

#ifdef __cplusplus
}
#endif
/*@}*/

#endif