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
28extern "C" {
29#endif
30
31/*
32 * Return values.
33 */
34typedef 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 */
47typedef 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 */
65typedef enum {
66	CCOP_COMCRYPT,
67	CCOP_DECOMCRYPT
68} comcryptOp;
69
70/*
71 * Used to specify End of stream.
72 */
73typedef 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 */
86typedef void *(comMallocExternFcn)(unsigned size);
87typedef void (comFreeExternFcn)(void *data);
88void comMallocRegister(comMallocExternFcn *mallocExtern,
89	comFreeExternFcn *freeExtern);
90
91/*
92 * Opaque data type for ComCryptData() and DeComCryptData()
93 */
94typedef void *comcryptObj;
95
96/*
97 * Call once at startup. The resulting comcryptObj can be reused multiple
98 * times.
99 */
100comcryptObj comcryptAlloc(void);
101
102/*
103 * Use this before starting every stream process
104 */
105comcryptReturn 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 */
114void 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 */
122unsigned 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 */
130unsigned 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 */
145comcryptReturn 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 */
163comcryptReturn 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_*/
176