OSX/libsecurity_comcryption/lib/comcryption.h

   1 /*
   2  * Copyright (c) 1997,2011-2012,2014 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _COMCRYPTION_H_
  25 #define _COMCRYPTION_H_
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /*
  32  * Return values.
  33  */
  34 typedef enum {
  35         CCR_SUCCESS = 0,                        // normal result
  36         CCR_OUTBUFFER_TOO_SMALL,        // caller needs to alloc more out buffer
  37         CCR_MEMORY_ERROR,                       // internal error
  38         CCR_WRONG_VERSION,                      // compatibility error
  39         CCR_BAD_CIPHERTEXT,                     // can't decrypt ciphertext stream
  40         CCR_INTERNAL                            // internal library error
  41 } comcryptReturn;
  42
  43 /*
  44  * Used to specify optimization in ComcryptInit(). May be ignored in
  45  * early implementation.
  46  */
  47 typedef enum {
  48         CCO_DEFAULT,                            // let the low-level code decide
  49         CCO_SIZE,                                       // optimize for max compression
  50         CCO_SECURITY,                           // optimize for max crypto security
  51         CCO_TIME,                                       // optimize for minimum runtime; implies no
  52                                                                 //   second-level comcryption; security not
  53                                                                 //   compromised
  54         CCO_TIME_SIZE,                          // minimum runtime with second-level
  55                                                                 //   comcryption enabled; implies loss of
  56                                                                 //   security
  57         CCO_ASCII,                                      // optimize for max compression for ASCII
  58                                                                 //   plaintext
  59         CCO_OTHER                                       // TBD
  60 } comcryptOptimize;
  61
  62 /*
  63  * Used to specify operation type.
  64  */
  65 typedef enum {
  66         CCOP_COMCRYPT,
  67         CCOP_DECOMCRYPT
  68 } comcryptOp;
  69
  70 /*
  71  * Used to specify End of stream.
  72  */
  73 typedef enum {
  74         CCE_MORE_TO_COME,                       // more ops to follow
  75         CCE_END_OF_STREAM                       // end of stream, close output strem
  76 } comcryptEos;
  77
  78 /*
  79  * Maximum key length in bytes.
  80  */
  81 #define COMCRYPT_MAX_KEYLENGTH  64
  82
  83 /*
  84  * Clients can *optionally* register external memory alloc/free functions here.
  85  */
  86 typedef void *(comMallocExternFcn)(unsigned size);
  87 typedef void (comFreeExternFcn)(void *data);
  88 void comMallocRegister(comMallocExternFcn *mallocExtern,
  89         comFreeExternFcn *freeExtern);
  90
  91 /*
  92  * Opaque data type for ComCryptData() and DeComCryptData()
  93  */
  94 typedef void *comcryptObj;
  95
  96 /*
  97  * Call once at startup. The resulting comcryptObj can be reused multiple
  98  * times.
  99  */
 100 comcryptObj comcryptAlloc(void);
 101
 102 /*
 103  * Use this before starting every stream process
 104  */
 105 comcryptReturn comcryptInit(
 106         comcryptObj             cobj,
 107     const unsigned char *key,
 108     unsigned            keyLen,
 109     comcryptOptimize    optimize);                      // CCO_SIZE, etc.
 110
 111 /*
 112  * Free a comcryptObj object obtained via comcryptAlloc()
 113  */
 114 void comcryptObjFree(comcryptObj cobj);
 115
 116 /*
 117  * Return the maximum input buffer size allowed for for specified
 118  * output buffer size. Note that for both comcrypt and decomcrypt,
 119  * to cover the worst case, the output buffer always has to be
 120  * larger that the input buffer.
 121  */
 122 unsigned comcryptMaxInBufSize(comcryptObj cobj,
 123     unsigned outBufSize,
 124     comcryptOp op);                                     // CCOP_COMCRYPT, etc.
 125
 126 /*
 127  * Return the maximum output buffer size for specified input buffer size.
 128  * Output buffer size will always be larger than input buffer size.
 129  */
 130 unsigned comcryptMaxOutBufSize(comcryptObj cobj,
 131     unsigned inBufSize,
 132     comcryptOp op,                                      // CCOP_COMCRYPT, etc.
 133         char final);                                    // nonzero for last op
 134                                                                         // only used for CCOP_DECOMCRYPT
 135
 136 /*
 137  * the one-function-fits-all comcrypt routine -
 138  * call it multiple times for one ComcryptObj if
 139  * you want, or just once to do a whole stream
 140  * in one shot.
 141  *
 142  * NOTE: in the current implementation, the endOfStream is not used;
 143  * no "final" call is necessary on comcryption.
 144  */
 145 comcryptReturn comcryptData(
 146         comcryptObj                     cobj,
 147         unsigned char                   *plainText,
 148         unsigned                                plainTextLen,
 149         unsigned char                   *cipherText,            // malloc'd by caller
 150         unsigned                                *cipherTextLen,         // IN/OUT
 151         comcryptEos                     endOfStream);           // CCE_END_OF_STREAM, etc.
 152
 153 /*
 154  * decomcrypt routine - call it multiple times for
 155  * one comcryptObj, or just once to do a whole stream
 156  * in one shot. Boundaries of ciphertext segments -
 157  * across calls to this function - are arbitrary.
 158  *
 159  * NOTE: in the current implementation, the final call to this (when
 160  * endOfStrem == CCE_END_OF_STREAM) must contain a nonzero amount of
 161  * ciphertext.
 162  */
 163 comcryptReturn deComcryptData(
 164         comcryptObj                     cobj,
 165         unsigned char                   *cipherText,
 166         unsigned                                cipherTextLen,
 167         unsigned char                   *plainText,
 168         unsigned                                *plainTextLen,          // IN/OUT
 169         comcryptEos                     endOfStream);           // CCE_END_OF_STREAM, etc.
 170
 171 #ifdef __cplusplus
 172 }
 173 #endif
 174
 175 #endif  /*_COMCRYPTION_H_*/