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_*/