CCCryptor(3cc) 3cc CCCryptor(3cc)

CCCryptorCreate, CCCryptorCreateFromData, CCCryptorRelease, CCCryptorUpdate, CCCryptorFinal, CCCryptorGetOutputLength, CCCryptorReset, CCCrypt — Common Cryptographic Algorithm Interfaces

These functions are found in libSystem.

#include <CommonCrypto/CommonCryptor.h>

CCCryptorStatus
CCCryptorCreate(CCOperation op, CCAlgorithm alg, CCOptions options, const void *key, size_t keyLength, const void *iv, CCCryptorRef *cryptorRef);

CCCryptorStatus
CCCryptorCreateFromData(CCOperation op, CCAlgorithm alg, CCOptions options, const void *key, size_t keyLength, const void *iv, const void *data, size_t dataLength, CCCryptorRef *cryptorRef, size_t *dataUsed);

CCCryptorStatus
CCCryptorCreateWithMode(CCOperation op, CCMode mode, CCAlgorithm alg"CCPadding padding, const void *iv, const void *key, size_t keyLength, const void *tweak, size_t tweakLength, int numRounds, CCModeOptions options, CCryptorRef *cryptorRef);

CCCryptorStatus
CCCryptorRelease(CCCryptorRef cryptorRef);

CCCryptorStatus
CCCryptorUpdate(CCCryptorRef cryptorRef, const void *dataIn, size_t dataInLength, void *dataOut, size_t dataOutAvailable, size_t *dataOutMoved);

CCCryptorStatus
CCCryptorFinal(CCCryptorRef cryptorRef, void *dataOut, size_t dataOutAvailable, size_t *dataOutMoved);

size_t
CCCryptorGetOutputLength(CCCryptorRef cryptorRef, size_t inputLength, bool final);

CCCryptorStatus
CCCryptorReset(CCCryptorRef cryptorRef, const void *iv);

CCCryptorStatus
CCCrypt(CCOperation op, CCAlgorithm alg, CCOptions options, const void *key, size_t keyLength, const void *iv, const void *dataIn, size_t dataInLength, void *dataOut, size_t dataOutAvailable, size_t *dataOutMoved);

This interface provides access to a number of symmetric encryption algorithms. Symmetric encryption algorithms come in two "flavors" - block ciphers, and stream ciphers. Block ciphers process data (while both encrypting and decrypting) in discrete chunks of data called blocks; stream ciphers operate on arbitrary sized data.

The object declared in this interface, () provides access to both block ciphers and stream ciphers with the same API; however some options are available for block ciphers that do not apply to stream ciphers.

The general operation of a call to () is: initialize it with raw key data and other optional fields with CCCryptorCreate() ; process input data via one or more calls to CCCryptorUpdate() each of which may result in output data being written to caller-supplied memory; and obtain possible remaining output data with () The CCCryptor is disposed of via () or in CBC and CTR modes (and only those modes), it can be reused (with the same key data as provided to CCCryptorCreate() ) by calling CCCryptorReset() CCCrypt() can be called.

CCCryptors can be dynamically allocated by this module, or their memory can be allocated by the caller.

A call to () or CCCrypt() will require a CCOperation , which can be either kCCEncrypt , or kCCDecrypt. The CCAlgorithm choice allows specification of the cipher to use, with kCCAlgorithmAES being the recommended choice. All supported stream ciphers (e.g., RC2 and RC4) are no longer considered secure and should not be used.

The options parameter is only used when specifying a block-cipher, and should be set to 0 if a stream-cipher is being used. Otherwise the following options are allowed, and may be ORed together. The options allow for the use of PKCS7 padding by setting the flag kCCOptionPKCS7Padding , and the use of the non-default mode of the cipher kCCOptionECBMode. This flag puts the cipher in Electronic Code Book mode and should not be used for encryption as this is known to be insecure, but rather it is provided to allow for direct access to the output of the block-cipher.

PKCS7; when padding is enabled, the total amount of data encrypted does not have to be an even multiple of the block size, and the actual length of plaintext is calculated during decryption.

If the ECB mode option is not specified, then by default block ciphers are used in Cipher Block Chaining mode, also known as CBC mode. When using CBC mode, an Initialization Vector (IV) should be provided along with the key when starting an encrypt or decrypt operation. The IV should be the same length in bytes as the block-cipher's length. If CBC mode is selected and no IV is provided, an IV of all zeroes will be used, which in many applications will result in security issues.

() also implements block buffering, so that individual calls to CCCryptorUpdate() do not have to provide data whose length is aligned to the block size. (If padding is disabled, encrypting with block ciphers does require that the *total* length of data input to CCCryptorUpdate() call(s) be aligned to the block size.)

Encryption and decryption can be performed "in-place", with the same buffer used for input and output. The () does not support in-place operation for ciphers modes that work with blocks of data such as CBC and ECB, because of block buffering.

A given () can only be used by one thread at a time; multiple threads can safely use different () at the same time.

CCCryptorRef objects created with () or CCCryptorCreateFromData() must be disposed of via () ; which clears sensitive data and deallocates the CCCryptorRef when the caller is finished using the CCCryptorRef.

() is used to encrypt or decrypt data. This routine can be called multiple times. The caller does not need to align input data lengths to block sizes; input is buffered as necessary for block ciphers.

When performing symmetric encryption with block ciphers, and padding is enabled via kCCOptionPKCS7Padding, the total number of bytes provided by all the calls to this function when encrypting can be arbitrary (i.e., the total number of bytes does not have to be block aligned). However if padding is disabled, or when decrypting, the total number of bytes does have to be aligned to the block size; otherwise () will return kCCAlignmentError.

A general rule for the size of the output buffer which must be provided by the caller is that for block ciphers, the output length is never larger than the input length plus the block size. For stream ciphers, the output length is always exactly the same as the input length. See the discussion for () for more information on this topic.

() finishes encryption and decryption operations and obtains the final data output. Except when kCCBufferTooSmall is returned, the CCCryptorRef can no longer be used for subsequent operations unless CCCryptorReset() is called on it, but this is only available in CBC or CTR mode.

It is not necessary to call () when performing symmetric encryption or decryption if padding is disabled, or when using a stream cipher.

It is not necessary to call () prior to () when aborting an operation.

Use () to determine output buffer size required to process a given input size. Some general rules apply that allow clients of this module to know a priori how much output buffer space will be required in a given situation. For stream ciphers, the output size is always equal to the input size, and CCCryptorFinal() never produces any data. For block ciphers, the output size will always be less than or equal to the input size plus the size of one block. For block ciphers, if the input size provided to each call to CCCryptorUpdate() is is an integral multiple of the block size, then the output size for each call to CCCryptorUpdate() is less than or equal to the input size for that call to CCCryptorUpdate(). CCCryptorFinal() only produces output when using a block cipher with padding enabled.

() reinitializes an existing CCCryptorRef with a (possibly) new initialization vector. The key contained in the CCCryptorRef is unchanged. This function is not implemented for any modes other than CBC or CTR, nor is it implemented for stream ciphers, and will return an error in such cases. This can be called on a CCCryptorRef with data pending (i.e. in a padded mode operation before CCCryptFinal() is called); however any pending data will be lost in that case.

() is a stateless, one-shot encrypt or decrypt operation. This basically performs a sequence of (), CCCryptorUpdate(), CCCryptorFinal(), and CCCryptorRelease().

If a mode other than CBC or ECB is desired, () can be used to specify other modes. Possible modes include Electronic Code Book, Cipher Block Chaining, Cipher Feedback, Output Feedback, and Counter Modes, which are specified by mode set respectively to:
kCCModeECB,
kCCModeCBC,
kCCModeCFB,
kCCModeCTR, and
kCCModeOFB.

In such calls, q.Ft tweak should be set to NULL, and tweakLength, numRounds and options are reserved for future use and must be set to 0. Padding is set as either ccNoPadding, or ccPKCS7Padding.

Formally, the following ciphers are supported in CCCryptor
kCCAlgorithmAES,
kCCAlgorithmDES,
kCCAlgorithm3DES,
kCCAlgorithmCAST,
kCCAlgorithmRC4,
kCCAlgorithmRC2, and
kCCAlgorithmBlowfish.

Caution should be used as several of these ciphers are only supported for legacy reasons, and are now often considered broken, or too weak for use (ie. DES, CAST, RC4, and RC2). The small block length 3DES, CAST and Blowfish requires their use only in specific cases. Similarly, CAST should only be used with 16 byte keys.

Block sizes, in bytes, for supported Ciphers. kCCBlockSizeAES128 is 16 bytes. kCCBlockSizeDES, kCCBlockSize3DES, and kCCBlockSizeCAST are all 8 bytes.

Key sizes supported for various ciphers are defined by the following constants, and must be given in fixed byte lengths. The following AES key bit length constants, define their corresponding byte equivalents:
kCCKeySizeAES128 = 16,
kCCKeySizeAES192 = 24, and
kCCKeySizeAES256 = 32.

DES and 3DES use
kCCKeySizeDES = 8, and
kCCKeySize3DES = 16, respectively.

For the remaining ciphers:
kCCKeySizeMinCAST = 5,
kCCKeySizeMaxCAST = 16,
kCCKeySizeMinRC4 = 1,
kCCKeySizeMaxRC4 = 512,
kCCKeySizeMinRC2 = 1,
kCCKeySizeMaxRC2 = 128,
kCCKeySizeMinBlowfish = 8, and
kCCKeySizeMaxBlowfish = 56,

define the relative minimum and maximum lengths of the keys. Note that any key shorter than 16 bytes frequently fails to provide suitable security guarantees. However, having a key of length 16 bytes does not ensure security. As mentioned earlier, many of the supported ciphers and modes are no longer considered secure.

Minimum context sizes, for caller-allocated CCCryptorRefs. To minimize dynamic allocation memory, a caller can create a by passing caller-supplied memory to the () function.

These constants define the minimum amount of memory, in bytes, needed for () for each supported cipher.

Note: these constants are valid for the current version of this library; they may change in subsequent releases, so applications wishing to allocate their own memory for use in creating CCCryptorRefs must be prepared to deal with a kCCBufferTooSmall returned from ()

kCCContextSizeAES128 - Minimum context size for kCCAlgorithmAES128. kCCContextSizeDES - Minimum context size for kCCAlgorithmDES. kCCContextSize3DES - Minimum context size for kCCAlgorithm3DES. kCCContextSizeCAST - Minimum context size for kCCAlgorithmCAST. kCCContextSizeRC4 - Minimum context size for kCCAlgorithmRC4.

The following values may be returned as a status of type CCCryptorStatus.

kCCSuccess - Operation completed normally.

kCCParamError - Illegal parameter value.

kCCBufferTooSmall - Insufficient buffer provided for specified operation.

kCCMemoryFailure - Memory allocation failure.

kCCAlignmentError - Input size was not aligned properly.

kCCDecodeError - Input data did not decode or decrypt properly.

kCCUnimplemented - Function not implemented for the current algorithm.

These functions are available in OS X 10.5 and later.

CCHmac(3cc), CC_MD5(3cc), CC_SHA(3cc), CC_crypto(3cc)

AES:
Federal Information Processing Standard FIPS PUB 197 (Advanced Encryption Standard),
DES:
Federal Information Processing Standard FIPS PUB 46-3 (Data Encryption Standard)
3DES:
NIST Special PublicationPUB 800-67 (Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher)
March 22, 2007 Mac OS X 12