--- name: "CCCryptor" section: "3cc" platform: "macos" package: "CommonCrypto" version: "600035" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/CCCryptor" --- # CCCryptor(3cc) Common Cryptographic Algorithm Interfaces ## NAME **CCCryptorCreate**, **CCCryptorCreateFromData**, **CCCryptorRelease**, **CCCryptorUpdate**, **CCCryptorFinal**, **CCCryptorGetOutputLength**, **CCCryptorReset**, **CCCrypt** – Common Cryptographic Algorithm Interfaces ## LIBRARY These functions are found in libSystem. ## SYNOPSIS **#include \** *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*); ## DESCRIPTION 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, **CCCryptor,**() 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 **CCCryptor**() 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 **CCCryptorFinal.**() The *CCCryptor* is disposed of via **CCCryptorRelease,**() 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 **CCCryptorCreate**() 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. **CCCryptor**() 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 **CCCryptorUpdate**() 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 **CCCryptor**() can only be used by one thread at a time; multiple threads can safely use different **CCCryptors**() at the same time. *CCCryptorRef* objects created with **CCCryptorCreate**() or **CCCryptorCreateFromData**() must be disposed of via **CCCRyptorRelease**() ; which clears sensitive data and deallocates the *CCCryptorRef* when the caller is finished using the *CCCryptorRef.* **CCCryptorUpdate**() 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 **CCCryptFinal**() 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 **CCCryptorGetOutputLength**() for more information on this topic. **CCCryptFinal**() 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 **CCCryptorFinal**() when performing symmetric encryption or decryption if padding is disabled, or when using a stream cipher. It is not necessary to call **CCCryptorFinal**() prior to **CCCryptorRelease**() when aborting an operation. Use **CCCryptorGetOutputLength**() 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. **CCCryptorReset**() 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. **CCCrypt**() is a stateless, one-shot encrypt or decrypt operation. This basically performs a sequence of **CCCrytorCreate**(), **CCCryptorUpdate**(), **CCCryptorFinal**(), and **CCCryptorRelease**(). If a mode other than CBC or ECB is desired, **CCCryptorCreateWithMode**() 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 **CCCryptorCreateFromData**() function. These constants define the minimum amount of memory, in bytes, needed for **CCCryptorRefs**() 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 **CCCryptorCreateFromData.**() *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. ## RETURN VALUES 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. ## HISTORY These functions are available in OS X 10.5 and later. ## SEE ALSO [CCHmac(3cc)](/CCHmac/3cc.md), [CC\_MD5(3cc)](/CC_MD5/3cc.md), [CC\_SHA(3cc)](/CC_SHA/3cc.md), [CC\_crypto(3cc)](/CC_crypto/3cc.md) ## STANDARDS - 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)