BeeCrypt  4.2.1
beecrypt.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 1999, 2000, 2001, 2002 X-Way Rights BV
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with this library; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  *
18  */
19 
30 #ifndef _BEECRYPT_H
31 #define _BEECRYPT_H
32 
33 #include "beecrypt/api.h"
34 
35 #include "beecrypt/memchunk.h"
36 #include "beecrypt/mpnumber.h"
37 
38 /*
39  * Entropy Sources
40  */
41 
46 typedef int (*entropyNext)(byte*, size_t);
47 
52 #ifdef __cplusplus
54 #else
55 struct _entropySource
56 #endif
57 {
61  const char* name;
66 };
67 
68 #ifndef __cplusplus
69 typedef struct _entropySource entropySource;
70 #endif
71 
72 #ifdef __cplusplus
73 extern "C" {
74 #endif
75 
82 int entropySourceCount(void);
83 
93 const entropySource* entropySourceGet(int n);
94 
101 const entropySource* entropySourceFind(const char* name);
102 
110 
123 int entropyGatherNext(byte*, size_t);
124 
125 #ifdef __cplusplus
126 }
127 #endif
128 
129 /*
130  * Pseudo-random Number Generators
131  */
132 
133 typedef void randomGeneratorParam;
134 
136 typedef int (*randomGeneratorSeed )(randomGeneratorParam*, const byte*, size_t);
137 typedef int (*randomGeneratorNext )(randomGeneratorParam*, byte*, size_t);
139 
140 /*
141  * The struct 'randomGenerator' holds information and pointers to code specific
142  * to each random generator. Each specific random generator MUST be written to
143  * be multithread safe.
144  *
145  * WARNING: each randomGenerator, when used in cryptographic applications, MUST
146  * be guaranteed to be of suitable quality and strength (i.e. don't use the
147  * random() function found in most UN*X-es).
148  *
149  * Multiple instances of each randomGenerator can be used (even concurrently),
150  * provided they each use their own randomGeneratorParam parameters, a chunk
151  * of memory which must be at least as large as indicated by the paramsize
152  * field.
153  *
154  */
155 
160 #ifdef __cplusplus
162 #else
163 struct _randomGenerator
164 #endif
165 {
169  const char* name;
175  const size_t paramsize;
192 };
193 
194 #ifndef __cplusplus
195 typedef struct _randomGenerator randomGenerator;
196 #endif
197 
198 /*
199  * You can use the following functions to find random generators implemented by
200  * the library:
201  *
202  * randomGeneratorCount returns the number of generators available.
203  *
204  * randomGeneratorGet returns the random generator with a given index (starting
205  * at zero, up to randomGeneratorCount() - 1), or NULL if the index was out of
206  * bounds.
207  *
208  * randomGeneratorFind returns the random generator with the given name, or
209  * NULL if no random generator exists with that name.
210  */
211 
212 #ifdef __cplusplus
213 extern "C" {
214 #endif
215 
217 int randomGeneratorCount(void);
221 const randomGenerator* randomGeneratorFind(const char*);
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 
229 /*
230  * The struct 'randomGeneratorContext' is used to contain both the functional
231  * part (the randomGenerator), and its parameters.
232  */
233 
234 #ifdef __cplusplus
236 #else
237 struct _randomGeneratorContext
238 #endif
239 {
242 
243  #ifdef __cplusplus
247  #endif
248 };
249 
250 #ifndef __cplusplus
251 typedef struct _randomGeneratorContext randomGeneratorContext;
252 #endif
253 
254 /*
255  * The following functions can be used to initialize and free a
256  * randomGeneratorContext. Initializing will allocate a buffer of the size
257  * required by the randomGenerator, freeing will deallocate that buffer.
258  */
259 
260 #ifdef __cplusplus
261 extern "C" {
262 #endif
263 
272 
273 #ifdef __cplusplus
274 }
275 #endif
276 
277 /*
278  * Hash Functions
279  */
280 
284 typedef void hashFunctionParam;
285 
287 typedef int (*hashFunctionUpdate)(hashFunctionParam*, const byte*, size_t);
289 
290 /*
291  * The struct 'hashFunction' holds information and pointers to code specific
292  * to each hash function. Specific hash functions MAY be written to be
293  * multithread-safe.
294  *
295  * NOTE: data MUST have a size (in bytes) of at least 'digestsize' as described
296  * in the hashFunction struct.
297  * NOTE: for safety reasons, after calling digest, each specific implementation
298  * MUST reset itself so that previous values in the parameters are erased.
299  */
300 #ifdef __cplusplus
302 #else
303 struct _hashFunction
304 #endif
305 {
306  const char* name;
307  const size_t paramsize; /* in bytes */
308  const size_t blocksize; /* in bytes */
309  const size_t digestsize; /* in bytes */
313 };
314 
315 #ifndef __cplusplus
316 typedef struct _hashFunction hashFunction;
317 #endif
318 
319 /*
320  * You can use the following functions to find hash functions implemented by
321  * the library:
322  *
323  * hashFunctionCount returns the number of hash functions available.
324  *
325  * hashFunctionGet returns the hash function with a given index (starting
326  * at zero, up to hashFunctionCount() - 1), or NULL if the index was out of
327  * bounds.
328  *
329  * hashFunctionFind returns the hash function with the given name, or
330  * NULL if no hash function exists with that name.
331  */
332 
333 #ifdef __cplusplus
334 extern "C" {
335 #endif
336 
338 int hashFunctionCount(void);
340 const hashFunction* hashFunctionGet(int);
342 const hashFunction* hashFunctionFind(const char*);
344 const hashFunction* hashFunctionDefault(void);
345 
346 #ifdef __cplusplus
347 }
348 #endif
349 
350 /*
351  * The struct 'hashFunctionContext' is used to contain both the functional
352  * part (the hashFunction), and its parameters.
353  */
354 #ifdef __cplusplus
356 #else
357 struct _hashFunctionContext
358 #endif
359 {
362 
363  #ifdef __cplusplus
367  #endif
368 };
369 
370 #ifndef __cplusplus
371 typedef struct _hashFunctionContext hashFunctionContext;
372 #endif
373 
374 /*
375  * The following functions can be used to initialize and free a
376  * hashFunctionContext. Initializing will allocate a buffer of the size
377  * required by the hashFunction, freeing will deallocate that buffer.
378  */
379 
380 #ifdef __cplusplus
381 extern "C" {
382 #endif
383 
402 
403 #ifdef __cplusplus
404 }
405 #endif
406 
407 /*
408  * Keyed Hash Functions, a.k.a. Message Authentication Codes
409  */
410 
415 
416 typedef int (*keyedHashFunctionSetup )(keyedHashFunctionParam*, const byte*, size_t);
418 typedef int (*keyedHashFunctionUpdate )(keyedHashFunctionParam*, const byte*, size_t);
420 
421 /*
422  * The struct 'keyedHashFunction' holds information and pointers to code
423  * specific to each keyed hash function. Specific keyed hash functions MAY be
424  * written to be multithread-safe.
425  *
426  * The struct field 'keybitsmin' contains the minimum number of bits a key
427  * must contains, 'keybitsmax' the maximum number of bits a key may contain,
428  * 'keybitsinc', the increment in bits that may be used between min and max.
429  *
430  * NOTE: data must be at least have a bytesize of 'digestsize' as described
431  * in the keyedHashFunction struct.
432  * NOTE: for safety reasons, after calling digest, each specific implementation
433  * MUST reset itself so that previous values in the parameters are erased.
434  */
435 #ifdef __cplusplus
437 #else
438 struct _keyedHashFunction
439 #endif
440 {
441  const char* name;
442  const size_t paramsize; /* in bytes */
443  const size_t blocksize; /* in bytes */
444  const size_t digestsize; /* in bytes */
445  const size_t keybitsmin; /* in bits */
446  const size_t keybitsmax; /* in bits */
447  const size_t keybitsinc; /* in bits */
452 };
453 
454 #ifndef __cplusplus
455 typedef struct _keyedHashFunction keyedHashFunction;
456 #endif
457 
458 /*
459  * You can use the following functions to find keyed hash functions implemented
460  * by the library:
461  *
462  * keyedHashFunctionCount returns the number of keyed hash functions available.
463  *
464  * keyedHashFunctionGet returns the keyed hash function with a given index
465  * (starting at zero, up to keyedHashFunctionCount() - 1), or NULL if the index
466  * was out of bounds.
467  *
468  * keyedHashFunctionFind returns the keyed hash function with the given name,
469  * or NULL if no keyed hash function exists with that name.
470  */
471 
472 #ifdef __cplusplus
473 extern "C" {
474 #endif
475 
477 int keyedHashFunctionCount(void);
481 const keyedHashFunction* keyedHashFunctionFind(const char*);
484 
485 #ifdef __cplusplus
486 }
487 #endif
488 
489 /*
490  * The struct 'keyedHashFunctionContext' is used to contain both the functional
491  * part (the keyedHashFunction), and its parameters.
492  */
493 #ifdef __cplusplus
495 #else
496 struct _keyedHashFunctionContext
497 #endif
498 {
501 
502  #ifdef __cplusplus
506  #endif
507 };
508 
509 #ifndef __cplusplus
510 typedef struct _keyedHashFunctionContext keyedHashFunctionContext;
511 #endif
512 
513 /*
514  * The following functions can be used to initialize and free a
515  * keyedHashFunctionContext. Initializing will allocate a buffer of the size
516  * required by the keyedHashFunction, freeing will deallocate that buffer.
517  */
518 
519 #ifdef __cplusplus
520 extern "C" {
521 #endif
522 
543 
544 #ifdef __cplusplus
545 }
546 #endif
547 
548 /*
549  * Block ciphers
550  */
551 
556 typedef enum
557 {
562 
568 typedef void blockCipherParam;
569 
573 typedef int (*blockCipherSetup )(blockCipherParam*, const byte*, size_t, cipherOperation);
574 
584 typedef int (*blockCipherSetIV )(blockCipherParam*, const byte*);
585 
596 typedef int (*blockCipherSetCTR )(blockCipherParam*, const byte*, size_t);
597 
598 
608 typedef int (*blockCipherRawcrypt)(blockCipherParam*, uint32_t*, const uint32_t*);
609 
621 typedef int (*blockCipherModcrypt)(blockCipherParam*, uint32_t*, const uint32_t*, unsigned int);
622 
623 typedef uint32_t* (*blockCipherFeedback)(blockCipherParam*);
624 
625 typedef struct
626 {
630 
631 typedef struct
632 {
636 
643 #ifdef __cplusplus
645 #else
646 struct _blockCipher
647 #endif
648 {
652  const char* name;
656  const size_t paramsize;
660  const size_t blocksize;
664  const size_t keybitsmin;
668  const size_t keybitsmax;
673  const size_t keybitsinc;
706 };
707 
708 #ifndef __cplusplus
709 typedef struct _blockCipher blockCipher;
710 #endif
711 
712 #ifdef __cplusplus
713 extern "C" {
714 #endif
715 
722 int blockCipherCount(void);
723 
733 const blockCipher* blockCipherGet(int);
734 
741 const blockCipher* blockCipherFind(const char*);
742 
749 const blockCipher* blockCipherDefault(void);
750 
751 #ifdef __cplusplus
752 }
753 #endif
754 
759 #ifdef __cplusplus
761 #else
762 struct _blockCipherContext
763 #endif
764 {
776 
777  #ifdef __cplusplus
781  #endif
782 };
783 
784 #ifndef __cplusplus
785 typedef struct _blockCipherContext blockCipherContext;
786 #endif
787 
788 /*
789  * The following functions can be used to initialize and free a
790  * blockCipherContext. Initializing will allocate a buffer of the size
791  * required by the blockCipher, freeing will deallocate that buffer.
792  */
793 
794 #ifdef __cplusplus
795 extern "C" {
796 #endif
797 
800 
803 
806 
808 int blockCipherContextSetCTR(blockCipherContext*, const byte*, size_t);
809 
812 
814 int blockCipherContextECB(blockCipherContext*, uint32_t*, const uint32_t*, int);
815 
817 int blockCipherContextCBC(blockCipherContext*, uint32_t*, const uint32_t*, int);
818 
820 int blockCipherContextCTR(blockCipherContext*, uint32_t*, const uint32_t*, int);
821 
824 
825 #ifdef __cplusplus
826 }
827 #endif
828 
829 #endif
int(* randomGeneratorNext)(randomGeneratorParam *, byte *, size_t)
Definition: beecrypt.h:137
uint32_t *(* blockCipherFeedback)(blockCipherParam *)
Definition: beecrypt.h:623
const char * name
The entropy source's name.
Definition: beecrypt.h:61
const blockCipherMode cbc
The cipher's CBC functions.
Definition: beecrypt.h:701
int blockCipherContextFree(blockCipherContext *)
const size_t paramsize
Definition: beecrypt.h:307
const hashFunction * hashFunctionDefault(void)
const blockCipherSetCTR setctr
Pointer to the cipher's ctr setup function.
Definition: beecrypt.h:685
void blockCipherParam
Placeholder type definition for blockcipher parameters.
Definition: beecrypt.h:568
keyedHashFunctionParam * param
Definition: beecrypt.h:500
cipherOperation
Specifies whether to perform encryption or decryption.
Definition: beecrypt.h:556
BeeCrypt API, portability headers.
cipherOperation op
Definition: beecrypt.h:775
int blockCipherContextValidKeylen(blockCipherContext *, size_t)
int(* keyedHashFunctionDigest)(keyedHashFunctionParam *, byte *)
Definition: beecrypt.h:419
void hashFunctionParam
Definition: beecrypt.h:284
int hashFunctionContextFree(hashFunctionContext *)
int blockCipherContextECB(blockCipherContext *, uint32_t *, const uint32_t *, int)
void keyedHashFunctionParam
Definition: beecrypt.h:414
This struct holds information and pointers to code specific to each pseudo-random number generator...
Definition: beecrypt.h:161
int keyedHashFunctionContextUpdateMP(keyedHashFunctionContext *, const mpnumber *)
int keyedHashFunctionContextUpdateMC(keyedHashFunctionContext *, const memchunk *)
int randomGeneratorContextInit(randomGeneratorContext *, const randomGenerator *)
Definition: beecrypt.h:560
Holds information and pointers to code specific to each cipher.
Definition: beecrypt.h:644
const blockCipherRawcrypt decrypt
Definition: beecrypt.h:628
int hashFunctionContextDigestMP(hashFunctionContext *, mpnumber *)
int(* hashFunctionReset)(hashFunctionParam *)
Definition: beecrypt.h:286
Holds a pointer to a blockcipher as well as its parameters.
Definition: beecrypt.h:760
int(* blockCipherSetup)(blockCipherParam *, const byte *, size_t, cipherOperation)
Prototype definition for a setup function.
Definition: beecrypt.h:573
const hashFunctionDigest digest
Definition: beecrypt.h:312
int keyedHashFunctionContextUpdate(keyedHashFunctionContext *, const byte *, size_t)
Definition: beecrypt.h:235
int entropyGatherNext(byte *, size_t)
This function gathers size bytes of entropy into data.
const entropySource * entropySourceFind(const char *name)
This function returns the entropy source specified by the given name.
Definition: beecrypt.h:436
const keyedHashFunction * keyedHashFunctionDefault(void)
const hashFunction * algo
Definition: beecrypt.h:360
const blockCipherSetIV setiv
Pointer to the cipher's initialization vector setup function.
Definition: beecrypt.h:681
blockCipherParam * param
Pointer to the parameters used by algo.
Definition: beecrypt.h:772
Definition: memchunk.h:28
int(* blockCipherSetCTR)(blockCipherParam *, const byte *, size_t)
Prototype definition for an initialization vector setup function.
Definition: beecrypt.h:596
int(* hashFunctionDigest)(hashFunctionParam *, byte *)
Definition: beecrypt.h:288
Definition: beecrypt.h:631
const entropySource * entropySourceGet(int n)
This function returns the n -th entropy source implemented by the library.
int(* entropyNext)(byte *, size_t)
Prototype definition for an entropy-generating function.
Definition: beecrypt.h:46
int keyedHashFunctionContextFree(keyedHashFunctionContext *)
const blockCipher * blockCipherFind(const char *)
This function returns the blockcipher specified by the given name.
int randomGeneratorContextFree(randomGeneratorContext *)
const char * name
Definition: beecrypt.h:441
Definition: beecrypt.h:355
const randomGenerator * rng
Definition: beecrypt.h:240
const keyedHashFunction * algo
Definition: beecrypt.h:499
Definition: beecrypt.h:625
int(* hashFunctionUpdate)(hashFunctionParam *, const byte *, size_t)
Definition: beecrypt.h:287
Definition: beecrypt.h:559
int blockCipherContextCBC(blockCipherContext *, uint32_t *, const uint32_t *, int)
const blockCipherMode ctr
The cipher's CTR functions.
Definition: beecrypt.h:705
const entropyNext next
Points to the function which produces the entropy.
Definition: beecrypt.h:65
int(* keyedHashFunctionSetup)(keyedHashFunctionParam *, const byte *, size_t)
Definition: beecrypt.h:416
const size_t keybitsmin
Definition: beecrypt.h:445
const blockCipherModcrypt decrypt
Definition: beecrypt.h:634
const randomGeneratorCleanup cleanup
Definition: beecrypt.h:191
int hashFunctionContextDigest(hashFunctionContext *, byte *)
const keyedHashFunctionReset reset
Definition: beecrypt.h:449
uint8_t byte
Definition: api.h:72
const blockCipherRaw raw
The cipher's raw functions.
Definition: beecrypt.h:693
Definition: beecrypt.h:494
const blockCipherFeedback getfb
Pointer to the cipher's feedback-returning function.
Definition: beecrypt.h:689
const char * name
Definition: beecrypt.h:306
const size_t paramsize
The size of the random generator's parameters.
Definition: beecrypt.h:175
randomGeneratorParam * param
Definition: beecrypt.h:241
const blockCipher * blockCipherDefault(void)
This functions returns the default blockcipher; the default value can be specified by setting environ...
int keyedHashFunctionContextSetup(keyedHashFunctionContext *, const byte *, size_t)
const keyedHashFunctionDigest digest
Definition: beecrypt.h:451
const char * name
The random generator's name.
Definition: beecrypt.h:169
const entropySource * entropySourceDefault(void)
This functions returns the default entropy source; the default value can be specified by setting envi...
int(* keyedHashFunctionUpdate)(keyedHashFunctionParam *, const byte *, size_t)
Definition: beecrypt.h:418
const blockCipherSetup setup
Pointer to the cipher's setup function.
Definition: beecrypt.h:677
const randomGeneratorNext next
Definition: beecrypt.h:187
int(* blockCipherModcrypt)(blockCipherParam *, uint32_t *, const uint32_t *, unsigned int)
Prototype for a encryption or decryption function which operates on multiple blocks in a certain mode...
Definition: beecrypt.h:621
Multi-precision numbers, headers.
const blockCipherMode ecb
The cipher's ECB functions.
Definition: beecrypt.h:697
int keyedHashFunctionContextDigestMP(keyedHashFunctionContext *, mpnumber *)
int(* blockCipherRawcrypt)(blockCipherParam *, uint32_t *, const uint32_t *)
Prototype for a raw encryption or decryption function.
Definition: beecrypt.h:608
int blockCipherContextInit(blockCipherContext *, const blockCipher *)
int hashFunctionCount(void)
int blockCipherContextCTR(blockCipherContext *, uint32_t *, const uint32_t *, int)
int keyedHashFunctionCount(void)
const keyedHashFunctionSetup setup
Definition: beecrypt.h:448
int hashFunctionContextUpdateMC(hashFunctionContext *, const memchunk *)
int entropySourceCount(void)
This function returns the number of entropy sources implemented by the library.
int hashFunctionContextInit(hashFunctionContext *, const hashFunction *)
const blockCipher * algo
Pointer to a blockCipher.
Definition: beecrypt.h:768
const randomGeneratorSeed seed
Points to the seeding function.
Definition: beecrypt.h:183
int(* randomGeneratorCleanup)(randomGeneratorParam *)
Definition: beecrypt.h:138
int(* keyedHashFunctionReset)(keyedHashFunctionParam *)
Definition: beecrypt.h:417
hashFunctionParam * param
Definition: beecrypt.h:361
const keyedHashFunction * keyedHashFunctionGet(int)
const size_t keybitsmax
Definition: beecrypt.h:446
int keyedHashFunctionContextDigest(keyedHashFunctionContext *, byte *)
const blockCipherModcrypt encrypt
Definition: beecrypt.h:633
int hashFunctionContextUpdate(hashFunctionContext *, const byte *, size_t)
const randomGenerator * randomGeneratorDefault(void)
int keyedHashFunctionContextReset(keyedHashFunctionContext *)
int(* randomGeneratorSeed)(randomGeneratorParam *, const byte *, size_t)
Definition: beecrypt.h:136
const size_t keybitsinc
Definition: beecrypt.h:447
const char * name
The blockcipher's name.
Definition: beecrypt.h:652
int blockCipherContextSetIV(blockCipherContext *, const byte *)
#define BEECRYPTAPI
Definition: api.h:52
int(* blockCipherSetIV)(blockCipherParam *, const byte *)
Prototype definition for an initialization vector setup function.
Definition: beecrypt.h:584
const size_t digestsize
Definition: beecrypt.h:444
const size_t keybitsinc
The allowed increment in key bits between min and max.
Definition: beecrypt.h:673
const size_t blocksize
Definition: beecrypt.h:443
int randomGeneratorContextNext(randomGeneratorContext *, byte *, size_t)
const blockCipherRawcrypt encrypt
Definition: beecrypt.h:627
int(* randomGeneratorSetup)(randomGeneratorParam *)
Definition: beecrypt.h:135
Definition: mpnumber.h:36
const size_t keybitsmin
The minimum number of key bits.
Definition: beecrypt.h:664
const size_t blocksize
The size of one block of data, in bytes.
Definition: beecrypt.h:660
const keyedHashFunctionUpdate update
Definition: beecrypt.h:450
int hashFunctionContextDigestMatch(hashFunctionContext *, const mpnumber *)
const size_t paramsize
The size of the parameters required by this cipher, in bytes.
Definition: beecrypt.h:656
const size_t paramsize
Definition: beecrypt.h:442
const size_t blocksize
Definition: beecrypt.h:308
Definition: beecrypt.h:301
const randomGenerator * randomGeneratorGet(int)
const hashFunctionUpdate update
Definition: beecrypt.h:311
Definition: beecrypt.h:558
const hashFunction * hashFunctionFind(const char *)
const size_t digestsize
Definition: beecrypt.h:309
int keyedHashFunctionContextDigestMatch(keyedHashFunctionContext *, const mpnumber *)
This struct holds information and pointers to code specific to each source of entropy.
Definition: beecrypt.h:53
int randomGeneratorContextSeed(randomGeneratorContext *, const byte *, size_t)
int keyedHashFunctionContextInit(keyedHashFunctionContext *, const keyedHashFunction *)
void randomGeneratorParam
Definition: beecrypt.h:133
int hashFunctionContextUpdateMP(hashFunctionContext *, const mpnumber *)
const hashFunctionReset reset
Definition: beecrypt.h:310
const hashFunction * hashFunctionGet(int)
int blockCipherContextSetup(blockCipherContext *, const byte *, size_t, cipherOperation)
int randomGeneratorCount(void)
const blockCipher * blockCipherGet(int)
This function returns the n -th blockcipher implemented by the library.
int blockCipherContextSetCTR(blockCipherContext *, const byte *, size_t)
const randomGeneratorSetup setup
Points to the setup function.
Definition: beecrypt.h:179
int hashFunctionContextReset(hashFunctionContext *)
const randomGenerator * randomGeneratorFind(const char *)
int blockCipherCount(void)
This function returns the number of blockciphers implemented by the library.
const size_t keybitsmax
The maximum number of key bits.
Definition: beecrypt.h:668
const keyedHashFunction * keyedHashFunctionFind(const char *)