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