mirror of
https://github.com/ziglang/zig.git
synced 2025-12-06 06:13:07 +00:00
764 lines
32 KiB
C
Vendored
764 lines
32 KiB
C
Vendored
/*
|
|
* Copyright (c) 2006-2010 Apple, Inc. All Rights Reserved.
|
|
*
|
|
* @APPLE_LICENSE_HEADER_START@
|
|
*
|
|
* This file contains Original Code and/or Modifications of Original Code
|
|
* as defined in and that are subject to the Apple Public Source License
|
|
* Version 2.0 (the 'License'). You may not use this file except in
|
|
* compliance with the License. Please obtain a copy of the License at
|
|
* http://www.opensource.apple.com/apsl/ and read it before using this
|
|
* file.
|
|
*
|
|
* The Original Code and all software distributed under the License are
|
|
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
|
|
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
|
|
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
|
|
* Please see the License for the specific language governing rights and
|
|
* limitations under the License.
|
|
*
|
|
* @APPLE_LICENSE_HEADER_END@
|
|
*/
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
|
|
#include <CommonCrypto/CommonCryptoError.h>
|
|
|
|
#ifndef _CC_COMMON_CRYPTOR_
|
|
#define _CC_COMMON_CRYPTOR_
|
|
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
|
|
#if defined(_MSC_VER)
|
|
#include <availability.h>
|
|
#else
|
|
#include <os/availability.h>
|
|
#endif
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*!
|
|
@typedef CCCryptorRef
|
|
@abstract Opaque reference to a CCCryptor object.
|
|
*/
|
|
typedef struct _CCCryptor *CCCryptorRef;
|
|
|
|
|
|
/*!
|
|
@enum CCOperation
|
|
@abstract Operations that an CCCryptor can perform.
|
|
|
|
@constant kCCEncrypt Symmetric encryption.
|
|
@constant kCCDecrypt Symmetric decryption.
|
|
*/
|
|
enum {
|
|
kCCEncrypt = 0,
|
|
kCCDecrypt,
|
|
};
|
|
typedef uint32_t CCOperation;
|
|
|
|
/*!
|
|
@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
|
|
*/
|
|
enum {
|
|
kCCAlgorithmAES128 = 0, /* Deprecated, name phased out due to ambiguity with key size */
|
|
kCCAlgorithmAES = 0,
|
|
kCCAlgorithmDES,
|
|
kCCAlgorithm3DES,
|
|
kCCAlgorithmCAST,
|
|
kCCAlgorithmRC4,
|
|
kCCAlgorithmRC2,
|
|
kCCAlgorithmBlowfish
|
|
};
|
|
typedef uint32_t CCAlgorithm;
|
|
|
|
/*!
|
|
@enum CCOptions
|
|
@abstract Options flags, passed to CCCryptorCreate().
|
|
|
|
@constant kCCOptionPKCS7Padding Perform PKCS7 padding.
|
|
@constant kCCOptionECBMode Electronic Code Book Mode.
|
|
Default is CBC.
|
|
*/
|
|
enum {
|
|
/* options for block ciphers */
|
|
kCCOptionPKCS7Padding = 0x0001,
|
|
kCCOptionECBMode = 0x0002
|
|
/* stream ciphers currently have no options */
|
|
};
|
|
typedef uint32_t CCOptions;
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
enum {
|
|
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 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.
|
|
*/
|
|
enum {
|
|
/* AES */
|
|
kCCBlockSizeAES128 = 16,
|
|
/* DES */
|
|
kCCBlockSizeDES = 8,
|
|
/* 3DES */
|
|
kCCBlockSize3DES = 8,
|
|
/* CAST */
|
|
kCCBlockSizeCAST = 8,
|
|
kCCBlockSizeRC2 = 8,
|
|
kCCBlockSizeBlowfish = 8,
|
|
};
|
|
|
|
/*!
|
|
@enum Minimum context sizes
|
|
@discussion Minimum context sizes, for caller-allocated CCCryptorRefs.
|
|
To minimize dynamic allocation memory, a caller can create
|
|
a CCCryptorRef 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 algorithm.
|
|
|
|
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 return from CCCryptorCreateFromData().
|
|
See discussion for the CCCryptorCreateFromData() function.
|
|
|
|
@constant kCCContextSizeAES128 - Minimum context size for kCCAlgorithmAES128.
|
|
@constant kCCContextSizeDES - Minimum context size for kCCAlgorithmDES.
|
|
@constant kCCContextSize3DES - Minimum context size for kCCAlgorithm3DES.
|
|
@constant kCCContextSizeCAST - Minimum context size for kCCAlgorithmCAST.
|
|
@constant kCCContextSizeRC4 - Minimum context size for kCCAlgorithmRC4.
|
|
*/
|
|
|
|
enum {
|
|
kCCContextSizeAES128 = 404,
|
|
kCCContextSizeDES = 240,
|
|
kCCContextSize3DES = 496,
|
|
kCCContextSizeCAST = 240,
|
|
kCCContextSizeRC4 = 1072
|
|
};
|
|
|
|
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
CCCryptorStatus CCCryptorCreate(
|
|
CCOperation op, /* kCCEncrypt, etc. */
|
|
CCAlgorithm alg, /* kCCAlgorithmDES, etc. */
|
|
CCOptions options, /* kCCOptionPKCS7Padding, etc. */
|
|
const void *key, /* raw key material */
|
|
size_t keyLength,
|
|
const void *iv, /* optional initialization vector */
|
|
CCCryptorRef *cryptorRef) /* RETURNED */
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
CCCryptorStatus CCCryptorCreateFromData(
|
|
CCOperation op, /* kCCEncrypt, etc. */
|
|
CCAlgorithm alg, /* kCCAlgorithmDES, etc. */
|
|
CCOptions options, /* kCCOptionPKCS7Padding, etc. */
|
|
const void *key, /* raw key material */
|
|
size_t keyLength,
|
|
const void *iv, /* optional initialization vector */
|
|
const void *data, /* caller-supplied memory */
|
|
size_t dataLength, /* length of data in bytes */
|
|
CCCryptorRef *cryptorRef, /* RETURNED */
|
|
size_t *dataUsed) /* optional, RETURNED */
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
CCCryptorStatus CCCryptorRelease(
|
|
CCCryptorRef cryptorRef)
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
CCCryptorStatus CCCryptorUpdate(
|
|
CCCryptorRef cryptorRef,
|
|
const void *dataIn,
|
|
size_t dataInLength,
|
|
void *dataOut, /* data RETURNED here */
|
|
size_t dataOutAvailable,
|
|
size_t *dataOutMoved) /* number of bytes written */
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
CCCryptorStatus CCCryptorFinal(
|
|
CCCryptorRef cryptorRef,
|
|
void *dataOut,
|
|
size_t dataOutAvailable,
|
|
size_t *dataOutMoved) /* number of bytes written */
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
size_t CCCryptorGetOutputLength(
|
|
CCCryptorRef cryptorRef,
|
|
size_t inputLength,
|
|
bool final)
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
|
|
/*!
|
|
@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.
|
|
*/
|
|
CCCryptorStatus CCCryptorReset(
|
|
CCCryptorRef cryptorRef,
|
|
const void *iv)
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
|
|
/*!
|
|
@function CCCrypt
|
|
@abstract Stateless, one-shot encrypt or decrypt operation.
|
|
This basically performs a sequence of CCCrytorCreate(),
|
|
CCCryptorUpdate(), CCCryptorFinal(), and CCCryptorRelease().
|
|
|
|
@param alg Defines the encryption algorithm.
|
|
|
|
|
|
@param op Defines the basic operation: kCCEncrypt or
|
|
kCCDecrypt.
|
|
|
|
@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 select algorithm. Some algorithms may
|
|
provide for varying key lengths.
|
|
|
|
@param iv Initialization vector, optional. Used for
|
|
Cipher Block Chaining (CBC) mode. If present,
|
|
must be the same length as the selected
|
|
algorithm's block size. If CBC mode is
|
|
selected (by the absence of any mode bits in
|
|
the options flags) and no IV is present, a
|
|
NULL (all zeroes) IV will be used. This 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 dataIn Data to encrypt or decrypt, length dataInLength
|
|
bytes.
|
|
|
|
@param dataInLength Length of data to encrypt or decrypt.
|
|
|
|
@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.
|
|
|
|
@param dataOutAvailable The size of the dataOut buffer in bytes.
|
|
|
|
@param dataOutMoved On successful return, the number of bytes
|
|
written to dataOut. If kCCBufferTooSmall is
|
|
returned as a result of insufficient buffer
|
|
space being provided, the required buffer space
|
|
is returned here.
|
|
|
|
@result kCCBufferTooSmall indicates insufficent space in the dataOut
|
|
buffer. In this case, the *dataOutMoved
|
|
parameter will indicate the size of the buffer
|
|
needed to complete the operation. The
|
|
operation can be retried with minimal runtime
|
|
penalty.
|
|
kCCAlignmentError indicates that dataInLength was not properly
|
|
aligned. This can only be returned for block
|
|
ciphers, and then only when decrypting or when
|
|
encrypting with block with padding disabled.
|
|
kCCDecodeError Indicates improperly formatted ciphertext or
|
|
a "wrong key" error; occurs only during decrypt
|
|
operations.
|
|
*/
|
|
|
|
CCCryptorStatus CCCrypt(
|
|
CCOperation op, /* kCCEncrypt, etc. */
|
|
CCAlgorithm alg, /* kCCAlgorithmAES128, etc. */
|
|
CCOptions options, /* kCCOptionPKCS7Padding, etc. */
|
|
const void *key,
|
|
size_t keyLength,
|
|
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)
|
|
API_AVAILABLE(macos(10.4), ios(2.0));
|
|
|
|
|
|
/*!
|
|
@enum Cipher Modes
|
|
@discussion These are the selections available for modes of operation for
|
|
use with block ciphers. If RC4 is selected as the cipher (a stream
|
|
cipher) the only correct mode is kCCModeRC4.
|
|
|
|
@constant kCCModeECB - Electronic Code Book Mode.
|
|
@constant kCCModeCBC - Cipher Block Chaining Mode.
|
|
@constant kCCModeCFB - Cipher Feedback Mode.
|
|
@constant kCCModeOFB - Output Feedback Mode.
|
|
@constant kCCModeRC4 - RC4 as a streaming cipher is handled internally as a mode.
|
|
@constant kCCModeCFB8 - Cipher Feedback Mode producing 8 bits per round.
|
|
*/
|
|
|
|
|
|
enum {
|
|
kCCModeECB = 1,
|
|
kCCModeCBC = 2,
|
|
kCCModeCFB = 3,
|
|
kCCModeCTR = 4,
|
|
kCCModeOFB = 7,
|
|
kCCModeRC4 = 9,
|
|
kCCModeCFB8 = 10,
|
|
};
|
|
typedef uint32_t CCMode;
|
|
|
|
/*!
|
|
@enum Padding for Block Ciphers
|
|
@discussion These are the padding options available for block modes.
|
|
|
|
@constant ccNoPadding - No padding.
|
|
@constant ccPKCS7Padding - PKCS7 Padding.
|
|
*/
|
|
|
|
enum {
|
|
ccNoPadding = 0,
|
|
ccPKCS7Padding = 1,
|
|
};
|
|
typedef uint32_t CCPadding;
|
|
|
|
/*!
|
|
@enum Mode options - Not currently in use.
|
|
|
|
@discussion Values used to specify options for modes. This was used for counter
|
|
mode operations in 10.8, now only Big Endian mode is supported.
|
|
|
|
@constant kCCModeOptionCTR_BE - CTR Mode Big Endian.
|
|
*/
|
|
|
|
enum {
|
|
kCCModeOptionCTR_BE = 2
|
|
};
|
|
|
|
typedef uint32_t CCModeOptions;
|
|
|
|
/*!
|
|
@function CCCryptorCreateWithMode
|
|
@abstract Create a cryptographic context.
|
|
|
|
@param op Defines the basic operation: kCCEncrypt or
|
|
kCCDecrypt.
|
|
|
|
@param mode Specifies the cipher mode to use for operations.
|
|
|
|
@param alg Defines the algorithm.
|
|
|
|
@param padding Specifies the padding to use.
|
|
|
|
@param iv Initialization vector, optional. Used by
|
|
block ciphers with the following modes:
|
|
|
|
Cipher Block Chaining (CBC)
|
|
Cipher Feedback (CFB and CFB8)
|
|
Output Feedback (OFB)
|
|
Counter (CTR)
|
|
|
|
If present, must be the same length as the selected
|
|
algorithm's block size. If no IV is present, a NULL
|
|
(all zeroes) IV will be used. For sound encryption,
|
|
always initialize iv with random data.
|
|
|
|
This parameter is ignored if ECB mode is used or
|
|
if a stream cipher algorithm is selected.
|
|
|
|
@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 tweak Raw key material, length keyLength bytes. Used for the
|
|
tweak key in XEX-based Tweaked CodeBook (XTS) mode.
|
|
|
|
@param tweakLength Length of tweak key material. Must be appropriate
|
|
for the selected operation and algorithm. Some
|
|
algorithms provide for varying key lengths. For XTS
|
|
this is the same length as the encryption key.
|
|
|
|
@param numRounds The number of rounds of the cipher to use. 0 uses the default.
|
|
|
|
@param options A word of flags defining options. See discussion
|
|
for the CCModeOptions type.
|
|
|
|
@param cryptorRef A (required) pointer to the returned CCCryptorRef.
|
|
|
|
@result Possible error returns are kCCParamError and kCCMemoryFailure.
|
|
*/
|
|
|
|
|
|
CCCryptorStatus CCCryptorCreateWithMode(
|
|
CCOperation op, /* kCCEncrypt, kCCDecrypt */
|
|
CCMode mode,
|
|
CCAlgorithm alg,
|
|
CCPadding padding,
|
|
const void *iv, /* optional initialization vector */
|
|
const void *key, /* raw key material */
|
|
size_t keyLength,
|
|
const void *tweak, /* raw tweak material */
|
|
size_t tweakLength,
|
|
int numRounds, /* 0 == default */
|
|
CCModeOptions options,
|
|
CCCryptorRef *cryptorRef) /* RETURNED */
|
|
API_AVAILABLE(macos(10.7), ios(5.0));
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _CC_COMMON_CRYPTOR_ */
|