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,
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.
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.
March 22, 2007 | macOS 14.6 |