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
46typedef int (*entropyNext)(byte*, size_t);
47
52#ifdef __cplusplus
54#else
55struct _entropySource
56#endif
57{
61 const char* name;
66};
67
68#ifndef __cplusplus
69typedef struct _entropySource entropySource;
70#endif
71
72#ifdef __cplusplus
73extern "C" {
74#endif
75
83
94
101const entropySource* entropySourceFind(const char* name);
102
110
123int entropyGatherNext(byte*, size_t);
124
125#ifdef __cplusplus
126}
127#endif
128
129/*
130 * Pseudo-random Number Generators
131 */
132
134
136typedef int (*randomGeneratorSeed )(randomGeneratorParam*, const byte*, size_t);
137typedef 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
163struct _randomGenerator
164#endif
165{
169 const char* name;
175 const size_t paramsize;
192};
193
194#ifndef __cplusplus
195typedef 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
213extern "C" {
214#endif
215
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
237struct _randomGeneratorContext
238#endif
239{
242
243 #ifdef __cplusplus
247 #endif
248};
249
250#ifndef __cplusplus
251typedef 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
261extern "C" {
262#endif
263
272
273#ifdef __cplusplus
274}
275#endif
276
277/*
278 * Hash Functions
279 */
280
284typedef void hashFunctionParam;
285
287typedef int (*hashFunctionUpdate)(hashFunctionParam*, const byte*, size_t);
288typedef int (*hashFunctionDigest)(hashFunctionParam*, byte*);
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
303struct _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
316typedef 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
334extern "C" {
335#endif
336
342const hashFunction* hashFunctionFind(const char*);
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
357struct _hashFunctionContext
358#endif
359{
362
363 #ifdef __cplusplus
367 #endif
368};
369
370#ifndef __cplusplus
371typedef 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
381extern "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
416typedef int (*keyedHashFunctionSetup )(keyedHashFunctionParam*, const byte*, size_t);
418typedef 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
438struct _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
455typedef 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
473extern "C" {
474#endif
475
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
496struct _keyedHashFunctionContext
497#endif
498{
501
502 #ifdef __cplusplus
506 #endif
507};
508
509#ifndef __cplusplus
510typedef 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
520extern "C" {
521#endif
522
543
544#ifdef __cplusplus
545}
546#endif
547
548/*
549 * Block ciphers
550 */
551
562
568typedef void blockCipherParam;
569
573typedef int (*blockCipherSetup )(blockCipherParam*, const byte*, size_t, cipherOperation);
574
584typedef int (*blockCipherSetIV )(blockCipherParam*, const byte*);
585
596typedef int (*blockCipherSetCTR )(blockCipherParam*, const byte*, size_t);
597
598
608typedef int (*blockCipherRawcrypt)(blockCipherParam*, uint32_t*, const uint32_t*);
609
621typedef int (*blockCipherModcrypt)(blockCipherParam*, uint32_t*, const uint32_t*, unsigned int);
622
623typedef uint32_t* (*blockCipherFeedback)(blockCipherParam*);
624
630
636
643#ifdef __cplusplus
645#else
646struct _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
709typedef struct _blockCipher blockCipher;
710#endif
711
712#ifdef __cplusplus
713extern "C" {
714#endif
715
723
734
741const blockCipher* blockCipherFind(const char*);
742
750
751#ifdef __cplusplus
752}
753#endif
754
759#ifdef __cplusplus
761#else
762struct _blockCipherContext
763#endif
764{
776
777 #ifdef __cplusplus
781 #endif
782};
783
784#ifndef __cplusplus
785typedef 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
795extern "C" {
796#endif
797
800
803
806
809
812
814int blockCipherContextECB(blockCipherContext*, uint32_t*, const uint32_t*, int);
815
817int blockCipherContextCBC(blockCipherContext*, uint32_t*, const uint32_t*, int);
818
820int blockCipherContextCTR(blockCipherContext*, uint32_t*, const uint32_t*, int);
821
824
825#ifdef __cplusplus
826}
827#endif
828
829#endif
BeeCrypt API, portability headers.
#define BEECRYPTAPI
Definition api.h:52
int randomGeneratorCount(void)
int keyedHashFunctionContextInit(keyedHashFunctionContext *, const keyedHashFunction *)
int hashFunctionContextFree(hashFunctionContext *)
int hashFunctionContextReset(hashFunctionContext *)
int blockCipherContextCTR(blockCipherContext *, uint32_t *, const uint32_t *, int)
int(* blockCipherSetup)(blockCipherParam *, const byte *, size_t, cipherOperation)
Prototype definition for a setup function.
Definition beecrypt.h:573
int randomGeneratorContextSeed(randomGeneratorContext *, const byte *, size_t)
const keyedHashFunction * keyedHashFunctionFind(const char *)
const keyedHashFunction * keyedHashFunctionDefault(void)
int hashFunctionContextDigestMP(hashFunctionContext *, mpnumber *)
int(* randomGeneratorCleanup)(randomGeneratorParam *)
Definition beecrypt.h:138
int entropySourceCount(void)
This function returns the number of entropy sources implemented by the library.
int(* hashFunctionReset)(hashFunctionParam *)
Definition beecrypt.h:286
int hashFunctionContextUpdateMP(hashFunctionContext *, const mpnumber *)
int(* hashFunctionDigest)(hashFunctionParam *, byte *)
Definition beecrypt.h:288
int(* blockCipherSetIV)(blockCipherParam *, const byte *)
Definition beecrypt.h:584
int(* keyedHashFunctionSetup)(keyedHashFunctionParam *, const byte *, size_t)
Definition beecrypt.h:416
int blockCipherContextSetup(blockCipherContext *, const byte *, size_t, cipherOperation)
int(* keyedHashFunctionDigest)(keyedHashFunctionParam *, byte *)
Definition beecrypt.h:419
const blockCipher * blockCipherFind(const char *)
This function returns the blockcipher specified by the given name.
int(* entropyNext)(byte *, size_t)
Definition beecrypt.h:46
int entropyGatherNext(byte *, size_t)
This function gathers size bytes of entropy into data.
const blockCipher * blockCipherDefault(void)
This functions returns the default blockcipher; the default value can be specified by setting environ...
int(* randomGeneratorSetup)(randomGeneratorParam *)
Definition beecrypt.h:135
int hashFunctionContextDigest(hashFunctionContext *, byte *)
const randomGenerator * randomGeneratorDefault(void)
int randomGeneratorContextFree(randomGeneratorContext *)
int randomGeneratorContextNext(randomGeneratorContext *, byte *, size_t)
int(* randomGeneratorSeed)(randomGeneratorParam *, const byte *, size_t)
Definition beecrypt.h:136
int keyedHashFunctionContextUpdateMC(keyedHashFunctionContext *, const memchunk *)
const keyedHashFunction * keyedHashFunctionGet(int)
int keyedHashFunctionContextSetup(keyedHashFunctionContext *, const byte *, size_t)
int hashFunctionCount(void)
int(* keyedHashFunctionUpdate)(keyedHashFunctionParam *, const byte *, size_t)
Definition beecrypt.h:418
int keyedHashFunctionContextUpdate(keyedHashFunctionContext *, const byte *, size_t)
int blockCipherContextSetIV(blockCipherContext *, const byte *)
void hashFunctionParam
Definition beecrypt.h:284
const hashFunction * hashFunctionGet(int)
int(* keyedHashFunctionReset)(keyedHashFunctionParam *)
Definition beecrypt.h:417
int keyedHashFunctionContextDigestMatch(keyedHashFunctionContext *, const mpnumber *)
int(* randomGeneratorNext)(randomGeneratorParam *, byte *, size_t)
Definition beecrypt.h:137
int hashFunctionContextDigestMatch(hashFunctionContext *, const mpnumber *)
int blockCipherContextValidKeylen(blockCipherContext *, size_t)
int(* hashFunctionUpdate)(hashFunctionParam *, const byte *, size_t)
Definition beecrypt.h:287
int hashFunctionContextInit(hashFunctionContext *, const hashFunction *)
const hashFunction * hashFunctionFind(const char *)
const entropySource * entropySourceFind(const char *name)
This function returns the entropy source specified by the given name.
int keyedHashFunctionContextReset(keyedHashFunctionContext *)
const blockCipher * blockCipherGet(int)
This function returns the n -th blockcipher implemented by the library.
int blockCipherContextSetCTR(blockCipherContext *, const byte *, size_t)
const randomGenerator * randomGeneratorGet(int)
uint32_t *(* blockCipherFeedback)(blockCipherParam *)
Definition beecrypt.h:623
int keyedHashFunctionContextUpdateMP(keyedHashFunctionContext *, const mpnumber *)
int(* blockCipherModcrypt)(blockCipherParam *, uint32_t *, const uint32_t *, unsigned int)
Definition beecrypt.h:621
int blockCipherContextFree(blockCipherContext *)
int keyedHashFunctionCount(void)
cipherOperation
Definition beecrypt.h:557
@ DECRYPT
Definition beecrypt.h:560
@ ENCRYPT
Definition beecrypt.h:559
@ NOCRYPT
Definition beecrypt.h:558
void blockCipherParam
Definition beecrypt.h:568
int(* blockCipherSetCTR)(blockCipherParam *, const byte *, size_t)
Definition beecrypt.h:596
int blockCipherContextCBC(blockCipherContext *, uint32_t *, const uint32_t *, int)
void keyedHashFunctionParam
Definition beecrypt.h:414
const entropySource * entropySourceGet(int n)
This function returns the n -th entropy source implemented by the library.
int keyedHashFunctionContextDigestMP(keyedHashFunctionContext *, mpnumber *)
void randomGeneratorParam
Definition beecrypt.h:133
int keyedHashFunctionContextFree(keyedHashFunctionContext *)
int(* blockCipherRawcrypt)(blockCipherParam *, uint32_t *, const uint32_t *)
Definition beecrypt.h:608
int blockCipherContextECB(blockCipherContext *, uint32_t *, const uint32_t *, int)
int keyedHashFunctionContextDigest(keyedHashFunctionContext *, byte *)
const randomGenerator * randomGeneratorFind(const char *)
int blockCipherContextInit(blockCipherContext *, const blockCipher *)
int randomGeneratorContextInit(randomGeneratorContext *, const randomGenerator *)
const hashFunction * hashFunctionDefault(void)
int hashFunctionContextUpdateMC(hashFunctionContext *, const memchunk *)
const entropySource * entropySourceDefault(void)
This functions returns the default entropy source; the default value can be specified by setting envi...
int hashFunctionContextUpdate(hashFunctionContext *, const byte *, size_t)
int blockCipherCount(void)
This function returns the number of blockciphers implemented by the library.
Multi-precision numbers, headers.
Holds a pointer to a blockcipher as well as its parameters.
Definition beecrypt.h:764
cipherOperation op
Definition beecrypt.h:775
blockCipherParam * param
Pointer to the parameters used by algo.
Definition beecrypt.h:772
blockCipherContext(const blockCipher *)
const blockCipher * algo
Pointer to a blockCipher.
Definition beecrypt.h:768
Definition beecrypt.h:632
const blockCipherModcrypt decrypt
Definition beecrypt.h:634
const blockCipherModcrypt encrypt
Definition beecrypt.h:633
Definition beecrypt.h:626
const blockCipherRawcrypt decrypt
Definition beecrypt.h:628
const blockCipherRawcrypt encrypt
Definition beecrypt.h:627
Holds information and pointers to code specific to each cipher.
Definition beecrypt.h:648
const blockCipherSetup setup
Pointer to the cipher's setup function.
Definition beecrypt.h:677
const blockCipherMode ctr
The cipher's CTR functions.
Definition beecrypt.h:705
const size_t keybitsmin
The minimum number of key bits.
Definition beecrypt.h:664
const blockCipherRaw raw
The cipher's raw functions.
Definition beecrypt.h:693
const char * name
The blockcipher's name.
Definition beecrypt.h:652
const blockCipherMode cbc
The cipher's CBC functions.
Definition beecrypt.h:701
const size_t blocksize
The size of one block of data, in bytes.
Definition beecrypt.h:660
const blockCipherSetIV setiv
Pointer to the cipher's initialization vector setup function.
Definition beecrypt.h:681
const blockCipherMode ecb
The cipher's ECB functions.
Definition beecrypt.h:697
const blockCipherFeedback getfb
Pointer to the cipher's feedback-returning function.
Definition beecrypt.h:689
const size_t keybitsinc
The allowed increment in key bits between min and max.
Definition beecrypt.h:673
const size_t keybitsmax
The maximum number of key bits.
Definition beecrypt.h:668
const size_t paramsize
The size of the parameters required by this cipher, in bytes.
Definition beecrypt.h:656
const blockCipherSetCTR setctr
Pointer to the cipher's ctr setup function.
Definition beecrypt.h:685
This struct holds information and pointers to code specific to each source of entropy.
Definition beecrypt.h:57
const char * name
The entropy source's name.
Definition beecrypt.h:61
const entropyNext next
Points to the function which produces the entropy.
Definition beecrypt.h:65
Definition beecrypt.h:359
const hashFunction * algo
Definition beecrypt.h:360
hashFunctionContext(const hashFunction *)
hashFunctionParam * param
Definition beecrypt.h:361
Definition beecrypt.h:305
const size_t digestsize
Definition beecrypt.h:309
const size_t blocksize
Definition beecrypt.h:308
const hashFunctionDigest digest
Definition beecrypt.h:312
const char * name
Definition beecrypt.h:306
const hashFunctionUpdate update
Definition beecrypt.h:311
const hashFunctionReset reset
Definition beecrypt.h:310
const size_t paramsize
Definition beecrypt.h:307
Definition beecrypt.h:498
const keyedHashFunction * algo
Definition beecrypt.h:499
keyedHashFunctionParam * param
Definition beecrypt.h:500
keyedHashFunctionContext(const keyedHashFunction *)
Definition beecrypt.h:440
const char * name
Definition beecrypt.h:441
const size_t digestsize
Definition beecrypt.h:444
const size_t keybitsinc
Definition beecrypt.h:447
const keyedHashFunctionDigest digest
Definition beecrypt.h:451
const keyedHashFunctionReset reset
Definition beecrypt.h:449
const keyedHashFunctionUpdate update
Definition beecrypt.h:450
const size_t keybitsmin
Definition beecrypt.h:445
const keyedHashFunctionSetup setup
Definition beecrypt.h:448
const size_t paramsize
Definition beecrypt.h:442
const size_t keybitsmax
Definition beecrypt.h:446
const size_t blocksize
Definition beecrypt.h:443
Definition memchunk.h:29
Definition mpnumber.h:40
Definition beecrypt.h:239
randomGeneratorParam * param
Definition beecrypt.h:241
randomGeneratorContext(const randomGenerator *)
const randomGenerator * rng
Definition beecrypt.h:240
This struct holds information and pointers to code specific to each pseudo-random number generator.
Definition beecrypt.h:165
const char * name
The random generator's name.
Definition beecrypt.h:169
const randomGeneratorNext next
Definition beecrypt.h:187
const randomGeneratorSetup setup
Points to the setup function.
Definition beecrypt.h:179
const size_t paramsize
The size of the random generator's parameters.
Definition beecrypt.h:175
const randomGeneratorSeed seed
Points to the seeding function.
Definition beecrypt.h:183
const randomGeneratorCleanup cleanup
Definition beecrypt.h:191