1.Dd March 22, 2007 2.Dt CCCryptor 3cc 3.Os 4.Sh NAME 5.Nm CCCryptorCreate , 6.Nm CCryptorCreateFromData , 7.Nm CCCryptorRelease , 8.Nm CCCryptorUpdate , 9.Nm CCCryptorFinal , 10.Nm CCCryptorGetOutputLength , 11.Nm CCCryptorReset , 12.Nm CCCrypt 13.Nd Common Cryptographic Algorithm Interfaces 14.Sh LIBRARY 15These functions are found in libSystem. 16.Sh SYNOPSIS 17.In CommonCrypto/CommonCryptor.h 18.Ft CCCryptorStatus 19.Fn CCCryptorCreate "CCOperation op" "CCAlgorithm alg" "CCOptions options" \ 20"const void *key" "size_t keyLength" "const void *iv" "CCCryptorRef *cryptorRef" 21.Ft CCCryptorStatus 22.Fn CCCryptorCreateFromData "CCOperation op" "CCAlgorithm alg" "CCOptions options" \ 23"const void *key" "size_t keyLength" "const void *iv" "const void *data" \ 24"size_t dataLength" "CCCryptorRef *cryptorRef" "size_t *dataUsed" 25.Ft CCCryptorStatus 26.Fn CCCryptorRelease "CCCryptorRef cryptorRef" 27.Ft CCCryptorStatus 28.Fn CCCryptorUpdate "CCCryptorRef cryptorRef" "const void *dataIn" \ 29"size_t dataInLength" "void *dataOut" "size_t dataOutAvailable" "size_t *dataOutMoved" 30.Ft CCCryptorStatus 31.Fn CCCryptorFinal "CCCryptorRef cryptorRef" "void *dataOut" \ 32"size_t dataOutAvailable" "size_t *dataOutMoved" 33.Ft size_t 34.Fn CCCryptorGetOutputLength "CCCryptorRef cryptorRef" "size_t inputLength" "bool final" 35.Ft CCCryptorStatus 36.Fn CCCryptorReset "CCCryptorRef cryptorRef" "const void *iv" 37.Ft CCCryptorStatus 38.Fn CCCrypt "CCOperation op" "CCAlgorithm alg" "CCOptions options" "const void *key" \ 39"size_t keyLength" "const void *iv" "const void *dataIn" "size_t dataInLength" \ 40"void *dataOut" "size_t dataOutAvailable" "size_t *dataOutMoved" 41.Sh DESCRIPTION 42This interface provides access to a number of symmetric encryption 43algorithms. Symmetric encryption algorithms come in two "flavors" - 44block ciphers, and stream ciphers. Block ciphers process data 45(while both encrypting and decrypting) in discrete chunks of 46data called blocks; stream ciphers operate on arbitrary sized 47data. 48.Pp 49The object declared in this interface, CCCryptor, provides 50access to both block ciphers and stream ciphers with the same 51API; however some options are available for block ciphers that 52do not apply to stream ciphers. 53.Pp 54The general operation of a CCCryptor is: initialize it 55with raw key data and other optional fields with CCCryptorCreate(); 56process input data via one or more calls to CCCryptorUpdate(), 57each of which may result in output data being written to 58caller-supplied memory; and obtain possible remaining output data 59with CCCryptorFinal(). The CCCryptor is disposed of via 60CCCryptorRelease(), or it can be reused (with the same key data 61as provided to CCCryptorCreate()) by calling CCCryptorReset(). 62.Pp 63CCCryptors can be dynamically allocated by this module, or 64their memory can be allocated by the caller. 65.Pp 66One option for block ciphers is padding, as defined in PKCS7; 67when padding is enabled, the total amount of data encrypted 68does not have to be an even multiple of the block size, and 69the actual length of plaintext is calculated during decryption. 70.Pp 71Another option for block ciphers is Cipher Block Chaining, known 72as CBC mode. When using CBC mode, an Initialization Vector (IV) 73is provided along with the key when starting an encrypt 74or decrypt operation. If CBC mode is selected and no IV is 75provided, an IV of all zeroes will be used. 76.Pp 77CCCryptor also implements block bufferring, so that individual 78calls to CCCryptorUpdate() do not have to provide data whose length 79is aligned to the block size. (If padding is disabled, encrypting 80with block ciphers does require that the *total* length of data 81input to CCCryptorUpdate() call(s) be aligned to the block size.) 82.Pp 83A given CCCryptor can only be used by one thread at a time; 84multiple threads can use safely different CCCryptors at the 85same time. 86.Pp 87.Ft CCCryptorRef 88objects created with 89.Fn CCCryptorCreate 90or 91.Fn CCCryptorCreateFromData 92*may* be disposed of 93via 94.Fn CCCRyptorRelease 95; that call is not strictly necessary, but 96if it's not performed, good security practice dictates that the 97caller should zero the memory provided to create the 98.Ft CCCryptorRef 99when the caller is finished using the 100.Ft CCCryptorRef. 101.Pp 102.Fn CCCryptorUpdate 103is used to encrypt or decrypt data. This routine can be called multiple times. The caller does 104not need to align input data lengths to block sizes; input is 105bufferred as necessary for block ciphers. 106.Pp 107When performing symmetric encryption with block ciphers, 108and padding is enabled via 109.Ft kCCOptionPKCS7Padding, 110the total 111number of bytes provided by all the calls to this function 112when encrypting can be arbitrary (i.e., the total number 113of bytes does not have to be block aligned). However if 114padding is disabled, or when decrypting, the total number 115of bytes does have to be aligned to the block size; otherwise 116.Fn CCCryptFinal 117will return 118.Ft kCCAlignmentError. 119.Pp 120A general rule for the size of the output buffer which must be 121provided by the caller is that for block ciphers, the output 122length is never larger than the input length plus the block size. 123For stream ciphers, the output length is always exactly the same 124as the input length. See the discussion for 125.Fn CCCryptorGetOutputLength 126for more information on this topic. 127.Pp 128.Fn CCCryptFinal 129finishes encryption and decryption operations and obtains the final data output. 130Except when 131.Ft kCCBufferTooSmall 132is returned, the 133.Ft CCCryptorRef 134can no longer be used for subsequent operations unless 135.Fn CCCryptorReset 136is called on it. 137.Pp 138It is not necessary to call 139.Fn CCCryptorFinal 140when performing 141symmetric encryption or decryption if padding is disabled, or 142when using a stream cipher. 143.Pp 144It is not necessary to call 145.Fn CCCryptorFinal 146prior to 147.Fn CCCryptorRelease 148when aborting an operation. 149.Pp 150Use 151.Fn CCCryptorGetOutputLength 152to determine output buffer size required to process a given input size. 153Some general rules apply that allow clients of this module to 154know a priori how much output buffer space will be required 155in a given situation. For stream ciphers, the output size is 156always equal to the input size, and 157.Fn CCCryptorFinal 158never 159produces any data. For block ciphers, the output size will 160always be less than or equal to the input size plus the size 161of one block. For block ciphers, if the input size provided 162to each call to 163.Fn CCCryptorUpdate 164is is an integral multiple 165of the block size, then the output size for each call to 166.Fn CCCryptorUpdate 167is less than or equal to the input size 168for that call to 169.Fn CCCryptorUpdate . 170.Fn CCCryptorFinal 171only produces output when using a block cipher with padding enabled. 172.Pp 173.Fn CCCryptorReset 174reinitializes an existing 175.Ft CCCryptorRef 176with a (possibly) new initialization vector. The key contained in the 177.Ft CCCryptorRef 178is unchanged. This function is not implemented for stream ciphers. This can be called on a CCCryptorRef with data pending (i.e. 179in a padded mode operation before 180.Fn CCCryptFinal 181is called); however any pending data will be lost in that case. 182.Pp 183.Fn CCCrypt 184is a stateless, one-shot encrypt or decrypt operation. 185This basically performs a sequence of 186.Fn CCCrytorCreate , 187.Fn CCCryptorUpdate , 188.Fn CCCryptorFinal , 189and 190.Fn CCCryptorRelease . 191.Sh RETURN VALUES 192The following values may be returned as a status of type 193.Ft CCCryptorStatus . 194.Pp 195.Er kCCSuccess 196- Operation completed normally. 197.Pp 198.Er kCCParamError 199- Illegal parameter value. 200.Pp 201.Er kCCBufferTooSmall 202- Insufficent buffer provided for specified operation. 203.Pp 204.Er kCCMemoryFailure 205- Memory allocation failure. 206.Pp 207.Er kCCAlignmentError 208- Input size was not aligned properly. 209.Pp 210.Er kCCDecodeError 211- Input data did not decode or decrypt properly. 212.Pp 213.Er kCCUnimplemented 214- Function not implemented for the current algorithm. 215.Sh HISTORY 216These functions are available in OS X 10.5 and later. 217.Sh SEE ALSO 218.Xr CCHmac 3cc , 219.Xr CC_MD5 3cc , 220.Xr CC_SHA 3cc , 221.Xr CC_crypto 3cc 222.Sh STANDARDS 223.Bl -tag 224.It AES: 225Federal Information Processing Standard \s-1FIPS\s0 \s-1PUB\s0 197 (Advanced Encryption Standard), 226.It DES: 227Federal Information Processing Standard \s-1FIPS\s0 \s-1PUB\s0 46\-3 (Data Encryption Standard) 228.It 3DES: 229NIST Special Publication\s-1PUB\s0 800\-67 (Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher) 230.El 231