libsecurity_comcryption/lib/comcryption.h

   1 /*
   2         File:           comcryption.h
   3
   4         Contains:       interface for low-level comcryption engine
   5
   6         Written by:     Doug Mitchell
   7
   8         Copyright:      (c) 1997 by Apple Computer, Inc., all rights reserved.
   9
  10         Change History (most recent first):
  11
  12                 11/11/97        gab             Updated for MPW
  13                 10/29/97        dm              Created, based on work by R. Crandall,
  14                                                                 G. Brown, A. Perez
  15         To Do:
  16
  17 */
  18 #ifndef _COMCRYPTION_H_
  19 #define _COMCRYPTION_H_
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /*
  26  * Return values.
  27  */
  28 typedef enum {
  29         CCR_SUCCESS = 0,                        // normal result
  30         CCR_OUTBUFFER_TOO_SMALL,        // caller needs to alloc more out buffer
  31         CCR_MEMORY_ERROR,                       // internal error
  32         CCR_WRONG_VERSION,                      // compatibility error
  33         CCR_BAD_CIPHERTEXT,                     // can't decrypt ciphertext stream
  34         CCR_INTERNAL                            // internal library error
  35 } comcryptReturn;
  36
  37 /*
  38  * Used to specify optimization in ComcryptInit(). May be ignored in
  39  * early implementation.
  40  */
  41 typedef enum {
  42         CCO_DEFAULT,                            // let the low-level code decide
  43         CCO_SIZE,                                       // optimize for max compression
  44         CCO_SECURITY,                           // optimize for max crypto security
  45         CCO_TIME,                                       // optimize for minimum runtime; implies no
  46                                                                 //   second-level comcryption; security not
  47                                                                 //   compromised
  48         CCO_TIME_SIZE,                          // minimum runtime with second-level
  49                                                                 //   comcryption enabled; implies loss of
  50                                                                 //   security
  51         CCO_ASCII,                                      // optimize for max compression for ASCII
  52                                                                 //   plaintext
  53         CCO_OTHER                                       // TBD
  54 } comcryptOptimize;
  55
  56 /*
  57  * Used to specify operation type.
  58  */
  59 typedef enum {
  60         CCOP_COMCRYPT,
  61         CCOP_DECOMCRYPT
  62 } comcryptOp;
  63
  64 /*
  65  * Used to specify End of stream.
  66  */
  67 typedef enum {
  68         CCE_MORE_TO_COME,                       // more ops to follow
  69         CCE_END_OF_STREAM                       // end of stream, close output strem
  70 } comcryptEos;
  71
  72 /*
  73  * Maximum key length in bytes.
  74  */
  75 #define COMCRYPT_MAX_KEYLENGTH  64
  76
  77 /*
  78  * Clients can *optionally* register external memory alloc/free functions here.
  79  */
  80 typedef void *(comMallocExternFcn)(unsigned size);
  81 typedef void (comFreeExternFcn)(void *data);
  82 void comMallocRegister(comMallocExternFcn *mallocExtern,
  83         comFreeExternFcn *freeExtern);
  84
  85 /*
  86  * Opaque data type for ComCryptData() and DeComCryptData()
  87  */
  88 typedef void *comcryptObj;
  89
  90 /*
  91  * Call once at startup. The resulting comcryptObj can be reused multiple
  92  * times.
  93  */
  94 comcryptObj comcryptAlloc();
  95
  96 /*
  97  * Use this before starting every stream process
  98  */
  99 comcryptReturn comcryptInit(
 100         comcryptObj             cobj,
 101     const unsigned char *key,
 102     unsigned            keyLen,
 103     comcryptOptimize    optimize);                      // CCO_SIZE, etc.
 104
 105 /*
 106  * Free a comcryptObj object obtained via comcryptAlloc()
 107  */
 108 void comcryptObjFree(comcryptObj cobj);
 109
 110 /*
 111  * Return the maximum input buffer size allowed for for specified
 112  * output buffer size. Note that for both comcrypt and decomcrypt,
 113  * to cover the worst case, the output buffer always has to be
 114  * larger that the input buffer.
 115  */
 116 unsigned comcryptMaxInBufSize(comcryptObj cobj,
 117     unsigned outBufSize,
 118     comcryptOp op);                                     // CCOP_COMCRYPT, etc.
 119
 120 /*
 121  * Return the maximum output buffer size for specified input buffer size.
 122  * Output buffer size will always be larger than input buffer size.
 123  */
 124 unsigned comcryptMaxOutBufSize(comcryptObj cobj,
 125     unsigned inBufSize,
 126     comcryptOp op,                                      // CCOP_COMCRYPT, etc.
 127         char final);                                    // nonzero for last op
 128                                                                         // only used for CCOP_DECOMCRYPT
 129
 130 /*
 131  * the one-function-fits-all comcrypt routine -
 132  * call it multiple times for one ComcryptObj if
 133  * you want, or just once to do a whole stream
 134  * in one shot.
 135  *
 136  * NOTE: in the current implementation, the endOfStream is not used;
 137  * no "final" call is necessary on comcryption.
 138  */
 139 comcryptReturn comcryptData(
 140         comcryptObj                     cobj,
 141         unsigned char                   *plainText,
 142         unsigned                                plainTextLen,
 143         unsigned char                   *cipherText,            // malloc'd by caller
 144         unsigned                                *cipherTextLen,         // IN/OUT
 145         comcryptEos                     endOfStream);           // CCE_END_OF_STREAM, etc.
 146
 147 /*
 148  * decomcrypt routine - call it multiple times for
 149  * one comcryptObj, or just once to do a whole stream
 150  * in one shot. Boundaries of ciphertext segments -
 151  * across calls to this function - are arbitrary.
 152  *
 153  * NOTE: in the current implementation, the final call to this (when
 154  * endOfStrem == CCE_END_OF_STREAM) must contain a nonzero amount of
 155  * ciphertext.
 156  */
 157 comcryptReturn deComcryptData(
 158         comcryptObj                     cobj,
 159         unsigned char                   *cipherText,
 160         unsigned                                cipherTextLen,
 161         unsigned char                   *plainText,
 162         unsigned                                *plainTextLen,          // IN/OUT
 163         comcryptEos                     endOfStream);           // CCE_END_OF_STREAM, etc.
 164
 165 #ifdef __cplusplus
 166 }
 167 #endif
 168
 169 #endif  /*_COMCRYPTION_H_*/