#include <CommonCrypto/CommonCryptor.h> also included by
<CommonCrypto/CommonCrypto.h>CommonCrypto/CommonCryptor.h
@header CommonCryptor.h
@abstract Generic interface for symmetric encryption.
@discussion 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 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 it can be reused (with
the same key data as provided to CCCryptorCreate()) by calling
CCCryptorReset(). The CCCryptorReset() function only works for
the CBC and CTR modes. In other block cipher modes, it returns error.
CCCryptors can be dynamically allocated by this module, or
their memory can be allocated by the caller. See discussion for
CCCryptorCreate() and CCCryptorCreateFromData() for information
on CCCryptor allocation.
One option for block ciphers is padding, as defined in 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.
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.
macro_CC_COMMON_CRYPTOR_
#define _CC_COMMON_CRYPTOR_
typedefCCCryptorRef
@typedef CCCryptorRef
@abstract Opaque reference to a CCCryptor object.
typedef struct _CCCryptor *CCCryptorRef
enum(anonymous)
@enum CCOperation
@abstract Operations that an CCCryptor can perform.
@constant kCCEncrypt Symmetric encryption.
@constant kCCDecrypt Symmetric decryption.
| kCCEncrypt | 0 | |
| kCCDecrypt | 1 |
typedefCCOperation
typedef uint32_t CCOperation
enum(anonymous)
@enum CCAlgorithm
@abstract Encryption algorithms implemented by this module.
@constant kCCAlgorithmAES Advanced Encryption Standard, 128-bit block
@constant kCCAlgorithmAES128 Deprecated, name phased out due to ambiguity with key size
@constant kCCAlgorithmDES Data Encryption Standard
@constant kCCAlgorithm3DES Triple-DES, three key, EDE configuration
@constant kCCAlgorithmCAST CAST
@constant kCCAlgorithmRC4 RC4 stream cipher
@constant kCCAlgorithmBlowfish Blowfish block cipher
| kCCAlgorithmAES128 | 0 | Deprecated, name phased out due to ambiguity with key size |
| kCCAlgorithmAES | 0 | |
| kCCAlgorithmDES | 1 | |
| kCCAlgorithm3DES | 2 | |
| kCCAlgorithmCAST | 3 | |
| kCCAlgorithmRC4 | 4 | |
| kCCAlgorithmRC2 | 5 | |
| kCCAlgorithmBlowfish | 6 |
typedefCCAlgorithm
typedef uint32_t CCAlgorithm
enum(anonymous)
@enum CCOptions
@abstract Options flags, passed to CCCryptorCreate().
@constant kCCOptionPKCS7Padding Perform PKCS7 padding.
@constant kCCOptionECBMode Electronic Code Book Mode.
Default is CBC.
| kCCOptionPKCS7Padding | 1 | options for block ciphers |
| kCCOptionECBMode | 2 |
typedefCCOptions
typedef uint32_t CCOptions
enum(anonymous)
@enum Key sizes
@discussion Key sizes, in bytes, for supported algorithms. Use these
constants to select any keysize variants you wish to use
for algorithms that support them (ie AES-128, AES-192, AES-256)
@constant kCCKeySizeAES128 128 bit AES key size.
@constant kCCKeySizeAES192 192 bit AES key size.
@constant kCCKeySizeAES256 256 bit AES key size.
@constant kCCKeySizeDES DES key size.
@constant kCCKeySize3DES Triple DES key size.
@constant kCCKeySizeMinCAST CAST minimum key size.
@constant kCCKeySizeMaxCAST CAST maximum key size.
@constant kCCKeySizeMinRC4 RC4 minimum key size.
@constant kCCKeySizeMaxRC4 RC4 maximum key size.
@discussion DES and TripleDES have fixed key sizes.
AES has three discrete key sizes.
CAST and RC4 have variable key sizes.
| kCCKeySizeAES128 | 16 | |
| kCCKeySizeAES192 | 24 | |
| kCCKeySizeAES256 | 32 | |
| kCCKeySizeDES | 8 | |
| kCCKeySize3DES | 24 | |
| kCCKeySizeMinCAST | 5 | |
| kCCKeySizeMaxCAST | 16 | |
| kCCKeySizeMinRC4 | 1 | |
| kCCKeySizeMaxRC4 | 512 | |
| kCCKeySizeMinRC2 | 1 | |
| kCCKeySizeMaxRC2 | 128 | |
| kCCKeySizeMinBlowfish | 8 | |
| kCCKeySizeMaxBlowfish | 56 |
enum(anonymous)
@enum Block sizes
@discussion Block sizes, in bytes, for supported algorithms.
@constant kCCBlockSizeAES128 AES block size (currently, only 128-bit
blocks are supported).
@constant kCCBlockSizeDES DES block size.
@constant kCCBlockSize3DES Triple DES block size.
@constant kCCBlockSizeCAST CAST block size.
| kCCBlockSizeAES128 | 16 | AES |
| kCCBlockSizeDES | 8 | DES |
| kCCBlockSize3DES | 8 | 3DES |
| kCCBlockSizeCAST | 8 | CAST |
| kCCBlockSizeRC2 | 8 | |
| kCCBlockSizeBlowfish | 8 |
enum(anonymous)
| kCCContextSizeAES128 | 404 | |
| kCCContextSizeDES | 240 | |
| kCCContextSize3DES | 496 | |
| kCCContextSizeCAST | 240 | |
| kCCContextSizeRC4 | 1072 |
functionCCCryptorCreate
/* RETURNED */ API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCryptorCreate( /* kCCEncrypt, etc. */ CCOperation op, /* kCCAlgorithmDES, etc. */ /* kCCEncrypt, /* kCCOptionPKCS7Padding, etc. */ etc. */ CCAlgorithm alg, /* raw key material */ /* kCCAlgorithmDES, etc. */ CCOptions options, /* optional initialization vector */ /* kCCOptionPKCS7Padding, /* RETURNED */ etc. */ const void *key, /* raw key material */ size_t keyLength, const void *iv, /* optional initialization vector */ CCCryptorRef *cryptorRef )
@function CCCryptorCreate
@abstract Create a cryptographic context.
@param op Defines the basic operation: kCCEncrypt or
kCCDecrypt.
@param alg Defines the algorithm.
@param options A word of flags defining options. See discussion
for the CCOptions type.
@param key Raw key material, length keyLength bytes.
@param keyLength Length of key material. Must be appropriate
for the selected operation and algorithm. Some
algorithms provide for varying key lengths.
@param iv Initialization vector, optional. Used by
block ciphers when Cipher Block Chaining (CBC)
mode is enabled. If present, must be the same
length as the selected algorithm's block size.
If CBC mode is selected (by the absence of the
kCCOptionECBMode bit in the options flags) and no
IV is present, a NULL (all zeroes) IV will be used.
This parameter is ignored if ECB mode is used or
if a stream cipher algorithm is selected. For sound
encryption, always initialize iv with random data.
@param cryptorRef A (required) pointer to the returned CCCryptorRef.
@result Possible error returns are kCCParamError and kCCMemoryFailure.
functionCCCryptorCreateFromData
/* optional, RETURNED */ API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCryptorCreateFromData( /* kCCEncrypt, etc. */ CCOperation op, /* kCCAlgorithmDES, etc. */ /* kCCEncrypt, /* kCCOptionPKCS7Padding, etc. */ etc. */ CCAlgorithm alg, /* raw key material */ /* kCCAlgorithmDES, etc. */ CCOptions options, /* optional initialization vector */ /* kCCOptionPKCS7Padding, /* caller-supplied memory */ etc. */ const void *key, /* raw key material */ /* length of data in bytes */ size_t keyLength, /* RETURNED */ const void *iv, /* optional initialization vector */ /* optional, RETURNED */ const void *data, /* caller-supplied memory */ size_t dataLength, /* length of data in bytes */ CCCryptorRef *cryptorRef, /* RETURNED */ size_t *dataUsed )
@function CCCryptorCreateFromData
@abstract Create a cryptographic context using caller-supplied memory.
@param op Defines the basic operation: kCCEncrypt or
kCCDecrypt.
@param alg Defines the algorithm.
@param options A word of flags defining options. See discussion
for the CCOptions type.
@param key Raw key material, length keyLength bytes.
@param keyLength Length of key material. Must be appropriate
for the selected operation and algorithm. Some
algorithms provide for varying key lengths.
@param iv Initialization vector, optional. Used by
block ciphers when Cipher Block Chaining (CBC)
mode is enabled. If present, must be the same
length as the selected algorithm's block size.
If CBC mode is selected (by the absence of the
kCCOptionECBMode bit in the options flags) and no
IV is present, a NULL (all zeroes) IV will be used.
This parameter is ignored if ECB mode is used or
if a stream cipher algorithm is selected. For sound
encryption, always initialize iv with random data.
@param data A pointer to caller-supplied memory from which the
CCCryptorRef will be created.
@param dataLength The size of the caller-supplied memory in bytes.
@param cryptorRef A (required) pointer to the returned CCCryptorRef.
@param dataUsed Optional. If present, the actual number of bytes of
the caller-supplied memory which was consumed by
creation of the CCCryptorRef is returned here. Also,
if the supplied memory is of insufficent size to create
a CCCryptorRef, kCCBufferTooSmall is returned, and
the minimum required buffer size is returned via this
parameter if present.
@result Possible error returns are kCCParamError and kCCBufferTooSmall.
@discussion The CCCryptorRef created by this function must be disposed of
via CCCRyptorRelease which clears sensitive data and deallocates memory
when the caller is finished using the CCCryptorRef.
functionCCCryptorRelease
API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCryptorRelease(CCCryptorRef cryptorRef)
@function CCCryptorRelease
@abstract Free a context created by CCCryptorCreate or
CCCryptorCreateFromData().
@param cryptorRef The CCCryptorRef to release.
@result The only possible error return is kCCParamError resulting
from passing in a null CCCryptorRef.
functionCCCryptorUpdate
/* number of bytes written */ API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCryptorUpdate( CCCryptorRef cryptorRef, const void *dataIn, size_t dataInLength, /* data RETURNED here */ void *dataOut, /* data RETURNED here */ size_t dataOutAvailable, /* number of bytes written */ size_t *dataOutMoved )
@function CCCryptorUpdate
@abstract Process (encrypt, decrypt) some data. The result, if any,
is written to a caller-provided buffer.
@param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
CCCryptorCreateFromData().
@param dataIn Data to process, length dataInLength bytes.
@param dataInLength Length of data to process.
@param dataOut Result is written here. Allocated by caller.
Encryption and decryption can be performed
"in-place", with the same buffer used for
input and output. The in-place operation is not
suported for ciphers modes that work with blocks
of data such as CBC and ECB.
@param dataOutAvailable The size of the dataOut buffer in bytes.
@param dataOutMoved On successful return, the number of bytes
written to dataOut.
@result kCCBufferTooSmall indicates insufficent space in the dataOut
buffer. The caller can use
CCCryptorGetOutputLength() to determine the
required output buffer size in this case. The
operation can be retried; no state is lost
when this is returned.
@discussion 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
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.
Generally, when all data has been processed, call
CCCryptorFinal().
In the following cases, the CCCryptorFinal() is superfluous as
it will not yield any data nor return an error:
1. Encrypting or decrypting with a block cipher with padding
disabled, when the total amount of data provided to
CCCryptorUpdate() is an integral multiple of the block size.
2. Encrypting or decrypting with a stream cipher.
functionCCCryptorFinal
/* number of bytes written */ API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCryptorFinal( CCCryptorRef cryptorRef, void *dataOut, size_t dataOutAvailable, /* number of bytes written */ size_t *dataOutMoved )
@function CCCryptorFinal
@abstract Finish an encrypt or decrypt operation, and obtain the (possible)
final data output.
@param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
CCCryptorCreateFromData().
@param dataOut Result is written here. Allocated by caller.
@param dataOutAvailable The size of the dataOut buffer in bytes.
@param dataOutMoved On successful return, the number of bytes
written to dataOut.
@result kCCBufferTooSmall indicates insufficent space in the dataOut
buffer. The caller can use
CCCryptorGetOutputLength() to determine the
required output buffer size in this case. The
operation can be retried; no state is lost
when this is returned.
kCCAlignmentError When decrypting, or when encrypting with a
block cipher with padding disabled,
kCCAlignmentError will be returned if the total
number of bytes provided to CCCryptUpdate() is
not an integral multiple of the current
algorithm's block size.
kCCDecodeError Indicates garbled ciphertext or the
wrong key during decryption. This can only
be returned while decrypting with padding
enabled.
@discussion Except when kCCBufferTooSmall is returned, the CCCryptorRef
can no longer be used for subsequent operations unless
CCCryptorReset() is called on it.
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.
functionCCCryptorGetOutputLength
API_AVAILABLE(macos(10.4), ios(2.0)) size_t CCCryptorGetOutputLength(CCCryptorRef cryptorRef, size_t inputLength, bool final)
@function CCCryptorGetOutputLength
@abstract Determine output buffer size required to process a given input
size.
@param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
CCCryptorCreateFromData().
@param inputLength The length of data which will be provided to
CCCryptorUpdate().
@param final If false, the returned value will indicate the
output buffer space needed when 'inputLength'
bytes are provided to CCCryptorUpdate(). When
'final' is true, the returned value will indicate
the total combined buffer space needed when
'inputLength' bytes are provided to
CCCryptorUpdate() and then CCCryptorFinal() is
called.
@result The maximum buffer space need to perform CCCryptorUpdate() and
optionally CCCryptorFinal().
@discussion 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.
functionCCCryptorReset
API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCryptorReset(CCCryptorRef cryptorRef, const void *iv)
@function CCCryptorReset
@abstract Reinitializes an existing CCCryptorRef with a (possibly)
new initialization vector. The CCCryptorRef's key is
unchanged. Use only for CBC and CTR modes.
@param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
CCCryptorCreateFromData().
@param iv Optional initialization vector; if present, must
be the same size as the current algorithm's block
size. For sound encryption, always initialize iv with
random data.
@result The only possible errors are kCCParamError and
kCCUnimplemented. On macOS 10.13, iOS 11, watchOS 4 and tvOS 11 returns kCCUnimplemented
for modes other than CBC. On prior SDKs, returns kCCSuccess to preserve compatibility
@discussion 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.
functionCCCrypt
API_AVAILABLE(macos(10.4), ios(2.0)) CCCryptorStatus CCCrypt( /* kCCEncrypt, etc. */ CCOperation op, /* kCCAlgorithmAES128, etc. */ /* kCCEncrypt, /* kCCOptionPKCS7Padding, etc. */ etc. */ CCAlgorithm alg, /* kCCAlgorithmAES128, etc. */ CCOptions options, /* optional initialization vector */ /* kCCOptionPKCS7Padding, /* optional per op and alg */ etc. */ const void *key, size_t keyLength, /* data RETURNED here */ const void *iv, /* optional initialization vector */ const void *dataIn, /* optional per op and alg */ size_t dataInLength, void *dataOut, /* data RETURNED here */ size_t dataOutAvailable, size_t *dataOutMoved )
enum(anonymous)
| kCCModeECB | 1 | |
| kCCModeCBC | 2 | |
| kCCModeCFB | 3 | |
| kCCModeCTR | 4 | |
| kCCModeOFB | 7 | |
| kCCModeRC4 | 9 | |
| kCCModeCFB8 | 10 |
typedefCCMode
typedef uint32_t CCMode
enum(anonymous)
| ccNoPadding | 0 | |
| ccPKCS7Padding | 1 |
typedefCCPadding
typedef uint32_t CCPadding
enum(anonymous)
| kCCModeOptionCTR_BE | 2 |
typedefCCModeOptions
typedef uint32_t CCModeOptions
functionCCCryptorCreateWithMode
/* RETURNED */ API_AVAILABLE(macos(10.7), ios(5.0)) CCCryptorStatus CCCryptorCreateWithMode( /* kCCEncrypt, kCCDecrypt */ CCOperation op, /* kCCEncrypt, kCCDecrypt */ CCMode mode, CCAlgorithm alg, /* optional initialization vector */ CCPadding padding, /* raw key material */ const void *iv, /* optional initialization vector */ const void *key, /* raw key material */ /* raw tweak material */ size_t keyLength, const void *tweak, /* raw tweak material */ /* 0 == default */ size_t tweakLength, int numRounds, /* 0 == default */ /* RETURNED */ CCModeOptions options, CCCryptorRef *cryptorRef )