CCCryptor(3cc) LOCAL CCCryptor(3cc)

NAME
     CCCCCCrryyppttoorrCCrreeaattee, CCCCrryyppttoorrCCrreeaatteeFFrroommDDaattaa, CCCCCCrryyppttoorrRReelleeaassee,
     CCCCCCrryyppttoorrUUppddaattee, CCCCCCrryyppttoorrFFiinnaall, CCCCCCrryyppttoorrGGeettOOuuttppuuttLLeennggtthh,
     CCCCCCrryyppttoorrRReesseett, CCCCCCrryypptt - Common Cryptographic Algorithm Interfaces

LLIIBBRRAARRYY
     These functions are found in libSystem.

SYNOPSIS
     ##iinncclluuddee <>

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

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

     CCCryptorStatus
     CCCCCCrryyppttoorrRReelleeaassee(CCCryptorRef cryptorRef);

     CCCryptorStatus
     CCCCCCrryyppttoorrUUppddaattee(CCCryptorRef cryptorRef, const void *dataIn,
         sizet dataInLength, void *dataOut, sizet dataOutAvailable,
         sizet *dataOutMoved);

     CCCryptorStatus
     CCCCCCrryyppttoorrFFiinnaall(CCCryptorRef cryptorRef, void *dataOut,
         sizet dataOutAvailable, sizet *dataOutMoved);

     sizet
     CCCCCCrryyppttoorrGGeettOOuuttppuuttLLeennggtthh(CCCryptorRef cryptorRef, sizet inputLength,
         bool final);

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

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

DESCRIPTION
     This interface provides access to a number of symmetric encryption algo-
     rithms. 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 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 out-
     put data being written to caller-supplied memory; and obtain possible
     remaining output data with CCCryptorFinal(). The CCCryptor is disposed of
     via CCCryptorRelease(), or it can be reused (with the same key data as
     provided to CCCryptorCreate()) by calling CCCryptorReset().

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

     One option for block ciphers is padding, as defined in PKCS7; when pad-
     ding 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.

     Another option for block ciphers is Cipher Block Chaining, known as CBC
     mode. When using CBC mode, an Initialization Vector (IV) is provided
     along with the key when starting an encrypt or decrypt operation. If CBC
     mode is selected and no IV is provided, an IV of all zeroes will be used.

     CCCryptor also implements block bufferring, 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.)

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

     CCCryptorRef objects created with CCCCCCrryyppttoorrCCrreeaattee() or
     CCCCCCrryyppttoorrCCrreeaatteeFFrroommDDaattaa() *may* be disposed of via CCCCCCRRyyppttoorrRReelleeaassee() ;
     that call is not strictly necessary, but if it's not performed, good
     security practice dictates that the caller should zero the memory pro-
     vided to create the CCCryptorRef when the caller is finished using the
     CCCryptorRef.

     CCCCCCrryyppttoorrUUppddaattee() 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 bufferred 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 CCCCCCrryyppttFFiinnaall() 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 CCCCCCrryyppttoorrGGeettOOuuttppuuttLLeennggtthh() for more information on this
     topic.

     CCCCCCrryyppttFFiinnaall() 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
     CCCCCCrryyppttoorrRReesseett() is called on it.

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

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

     Use CCCCCCrryyppttoorrGGeettOOuuttppuuttLLeennggtthh() 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 CCCCCCrryyppttoorrFFiinnaall() 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 CCCCCCrryyppttoorrUUppddaattee() is is an inte-
     gral multiple of the block size, then the output size for each call to
     CCCCCCrryyppttoorrUUppddaattee() is less than or equal to the input size for that call
     to CCCCCCrryyppttoorrUUppddaattee().  CCCCCCrryyppttoorrFFiinnaall() only produces output when using a
     block cipher with padding enabled.

     CCCCCCrryyppttoorrRReesseett() reinitializes an existing CCCryptorRef with a (possibly)
     new initialization vector. The key contained in the CCCryptorRef is
     unchanged. This function is not implemented for stream ciphers.  This can
     be called on a CCCryptorRef with data pending (i.e.  in a padded mode
     operation before CCCCCCrryyppttFFiinnaall() is called); however any pending data will
     be lost in that case.

     CCCCCCrryypptt() is a stateless, one-shot encrypt or decrypt operation.  This
     basically performs a sequence of CCCCCCrryyttoorrCCrreeaattee(), CCCCCCrryyppttoorrUUppddaattee(),
     CCCCCCrryyppttoorrFFiinnaall(), and CCCCCCrryyppttoorrRReelleeaassee().

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

     kCCSuccess - Operation completed normally.

     kCCParamError - Illegal parameter value.

     kCCBufferTooSmall - Insufficent 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.

SEE ALSO
     CCHmac(3cc), CCMD5(3cc), CCSHA(3cc), CCcrypto(3cc)

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)

BSD                             March 22, 2007                             BSD