master
1/*
2 * Copyright (c) 2006-2010 Apple, Inc. All Rights Reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24/*!
25 @header CommonCryptor.h
26 @abstract Generic interface for symmetric encryption.
27
28 @discussion This interface provides access to a number of symmetric
29 encryption algorithms. Symmetric encryption algorithms come
30 in two "flavors" - block ciphers, and stream ciphers. Block
31 ciphers process data (while both encrypting and decrypting)
32 in discrete chunks of data called blocks; stream ciphers
33 operate on arbitrary sized data.
34
35 The object declared in this interface, CCCryptor, provides
36 access to both block ciphers and stream ciphers with the same
37 API; however some options are available for block ciphers that
38 do not apply to stream ciphers.
39
40 The general operation of a CCCryptor is: initialize it
41 with raw key data and other optional fields with
42 CCCryptorCreate(); process input data via one or more calls to
43 CCCryptorUpdate(), each of which may result in output data
44 being written to caller-supplied memory; and obtain possible
45 remaining output data with CCCryptorFinal(). The CCCryptor is
46 disposed of via CCCryptorRelease(), or it can be reused (with
47 the same key data as provided to CCCryptorCreate()) by calling
48 CCCryptorReset(). The CCCryptorReset() function only works for
49 the CBC and CTR modes. In other block cipher modes, it returns error.
50
51
52 CCCryptors can be dynamically allocated by this module, or
53 their memory can be allocated by the caller. See discussion for
54 CCCryptorCreate() and CCCryptorCreateFromData() for information
55 on CCCryptor allocation.
56
57 One option for block ciphers is padding, as defined in PKCS7;
58 when padding is enabled, the total amount of data encrypted
59 does not have to be an even multiple of the block size, and
60 the actual length of plaintext is calculated during decryption.
61
62 Another option for block ciphers is Cipher Block Chaining, known
63 as CBC mode. When using CBC mode, an Initialization Vector (IV)
64 is provided along with the key when starting an encrypt
65 or decrypt operation. If CBC mode is selected and no IV is
66 provided, an IV of all zeroes will be used.
67
68 CCCryptor also implements block bufferring, so that individual
69 calls to CCCryptorUpdate() do not have to provide data whose
70 length is aligned to the block size. (If padding is disabled,
71 encrypting with block ciphers does require that the *total*
72 length of data input to CCCryptorUpdate() call(s) be aligned
73 to the block size.)
74
75 A given CCCryptor can only be used by one thread at a time;
76 multiple threads can use safely different CCCryptors at the
77 same time.
78*/
79
80#include <CommonCrypto/CommonCryptoError.h>
81
82#ifndef _CC_COMMON_CRYPTOR_
83#define _CC_COMMON_CRYPTOR_
84
85#include <stdbool.h>
86#include <stdint.h>
87#include <stddef.h>
88
89#if defined(_MSC_VER)
90#include <availability.h>
91#else
92#include <os/availability.h>
93#endif
94
95
96#ifdef __cplusplus
97extern "C" {
98#endif
99
100/*!
101 @typedef CCCryptorRef
102 @abstract Opaque reference to a CCCryptor object.
103 */
104typedef struct _CCCryptor *CCCryptorRef;
105
106
107/*!
108 @enum CCOperation
109 @abstract Operations that an CCCryptor can perform.
110
111 @constant kCCEncrypt Symmetric encryption.
112 @constant kCCDecrypt Symmetric decryption.
113*/
114enum {
115 kCCEncrypt = 0,
116 kCCDecrypt,
117};
118typedef uint32_t CCOperation;
119
120/*!
121 @enum CCAlgorithm
122 @abstract Encryption algorithms implemented by this module.
123 @constant kCCAlgorithmAES Advanced Encryption Standard, 128-bit block
124 @constant kCCAlgorithmAES128 Deprecated, name phased out due to ambiguity with key size
125 @constant kCCAlgorithmDES Data Encryption Standard
126 @constant kCCAlgorithm3DES Triple-DES, three key, EDE configuration
127 @constant kCCAlgorithmCAST CAST
128 @constant kCCAlgorithmRC4 RC4 stream cipher
129 @constant kCCAlgorithmBlowfish Blowfish block cipher
130*/
131enum {
132 kCCAlgorithmAES128 = 0, /* Deprecated, name phased out due to ambiguity with key size */
133 kCCAlgorithmAES = 0,
134 kCCAlgorithmDES,
135 kCCAlgorithm3DES,
136 kCCAlgorithmCAST,
137 kCCAlgorithmRC4,
138 kCCAlgorithmRC2,
139 kCCAlgorithmBlowfish
140};
141typedef uint32_t CCAlgorithm;
142
143/*!
144 @enum CCOptions
145 @abstract Options flags, passed to CCCryptorCreate().
146
147 @constant kCCOptionPKCS7Padding Perform PKCS7 padding.
148 @constant kCCOptionECBMode Electronic Code Book Mode.
149 Default is CBC.
150*/
151enum {
152 /* options for block ciphers */
153 kCCOptionPKCS7Padding = 0x0001,
154 kCCOptionECBMode = 0x0002
155 /* stream ciphers currently have no options */
156};
157typedef uint32_t CCOptions;
158
159/*!
160 @enum Key sizes
161
162 @discussion Key sizes, in bytes, for supported algorithms. Use these
163 constants to select any keysize variants you wish to use
164 for algorithms that support them (ie AES-128, AES-192, AES-256)
165
166 @constant kCCKeySizeAES128 128 bit AES key size.
167 @constant kCCKeySizeAES192 192 bit AES key size.
168 @constant kCCKeySizeAES256 256 bit AES key size.
169 @constant kCCKeySizeDES DES key size.
170 @constant kCCKeySize3DES Triple DES key size.
171 @constant kCCKeySizeMinCAST CAST minimum key size.
172 @constant kCCKeySizeMaxCAST CAST maximum key size.
173 @constant kCCKeySizeMinRC4 RC4 minimum key size.
174 @constant kCCKeySizeMaxRC4 RC4 maximum key size.
175
176 @discussion DES and TripleDES have fixed key sizes.
177 AES has three discrete key sizes.
178 CAST and RC4 have variable key sizes.
179*/
180enum {
181 kCCKeySizeAES128 = 16,
182 kCCKeySizeAES192 = 24,
183 kCCKeySizeAES256 = 32,
184 kCCKeySizeDES = 8,
185 kCCKeySize3DES = 24,
186 kCCKeySizeMinCAST = 5,
187 kCCKeySizeMaxCAST = 16,
188 kCCKeySizeMinRC4 = 1,
189 kCCKeySizeMaxRC4 = 512,
190 kCCKeySizeMinRC2 = 1,
191 kCCKeySizeMaxRC2 = 128,
192 kCCKeySizeMinBlowfish = 8,
193 kCCKeySizeMaxBlowfish = 56,
194};
195
196/*!
197 @enum Block sizes
198
199 @discussion Block sizes, in bytes, for supported algorithms.
200
201 @constant kCCBlockSizeAES128 AES block size (currently, only 128-bit
202 blocks are supported).
203 @constant kCCBlockSizeDES DES block size.
204 @constant kCCBlockSize3DES Triple DES block size.
205 @constant kCCBlockSizeCAST CAST block size.
206*/
207enum {
208 /* AES */
209 kCCBlockSizeAES128 = 16,
210 /* DES */
211 kCCBlockSizeDES = 8,
212 /* 3DES */
213 kCCBlockSize3DES = 8,
214 /* CAST */
215 kCCBlockSizeCAST = 8,
216 kCCBlockSizeRC2 = 8,
217 kCCBlockSizeBlowfish = 8,
218};
219
220/*!
221 @enum Minimum context sizes
222 @discussion Minimum context sizes, for caller-allocated CCCryptorRefs.
223 To minimize dynamic allocation memory, a caller can create
224 a CCCryptorRef by passing caller-supplied memory to the
225 CCCryptorCreateFromData() function.
226
227 These constants define the minimum amount of memory, in
228 bytes, needed for CCCryptorRefs for each supported algorithm.
229
230 Note: these constants are valid for the current version of
231 this library; they may change in subsequent releases, so
232 applications wishing to allocate their own memory for use
233 in creating CCCryptorRefs must be prepared to deal with
234 a kCCBufferTooSmall return from CCCryptorCreateFromData().
235 See discussion for the CCCryptorCreateFromData() function.
236
237 @constant kCCContextSizeAES128 - Minimum context size for kCCAlgorithmAES128.
238 @constant kCCContextSizeDES - Minimum context size for kCCAlgorithmDES.
239 @constant kCCContextSize3DES - Minimum context size for kCCAlgorithm3DES.
240 @constant kCCContextSizeCAST - Minimum context size for kCCAlgorithmCAST.
241 @constant kCCContextSizeRC4 - Minimum context size for kCCAlgorithmRC4.
242*/
243
244enum {
245 kCCContextSizeAES128 = 404,
246 kCCContextSizeDES = 240,
247 kCCContextSize3DES = 496,
248 kCCContextSizeCAST = 240,
249 kCCContextSizeRC4 = 1072
250};
251
252
253
254/*!
255 @function CCCryptorCreate
256 @abstract Create a cryptographic context.
257
258 @param op Defines the basic operation: kCCEncrypt or
259 kCCDecrypt.
260
261 @param alg Defines the algorithm.
262
263 @param options A word of flags defining options. See discussion
264 for the CCOptions type.
265
266 @param key Raw key material, length keyLength bytes.
267
268 @param keyLength Length of key material. Must be appropriate
269 for the selected operation and algorithm. Some
270 algorithms provide for varying key lengths.
271
272 @param iv Initialization vector, optional. Used by
273 block ciphers when Cipher Block Chaining (CBC)
274 mode is enabled. If present, must be the same
275 length as the selected algorithm's block size.
276 If CBC mode is selected (by the absence of the
277 kCCOptionECBMode bit in the options flags) and no
278 IV is present, a NULL (all zeroes) IV will be used.
279 This parameter is ignored if ECB mode is used or
280 if a stream cipher algorithm is selected. For sound
281 encryption, always initialize iv with random data.
282
283 @param cryptorRef A (required) pointer to the returned CCCryptorRef.
284
285 @result Possible error returns are kCCParamError and kCCMemoryFailure.
286*/
287CCCryptorStatus CCCryptorCreate(
288 CCOperation op, /* kCCEncrypt, etc. */
289 CCAlgorithm alg, /* kCCAlgorithmDES, etc. */
290 CCOptions options, /* kCCOptionPKCS7Padding, etc. */
291 const void *key, /* raw key material */
292 size_t keyLength,
293 const void *iv, /* optional initialization vector */
294 CCCryptorRef *cryptorRef) /* RETURNED */
295API_AVAILABLE(macos(10.4), ios(2.0));
296
297/*!
298 @function CCCryptorCreateFromData
299 @abstract Create a cryptographic context using caller-supplied memory.
300
301 @param op Defines the basic operation: kCCEncrypt or
302 kCCDecrypt.
303
304 @param alg Defines the algorithm.
305
306 @param options A word of flags defining options. See discussion
307 for the CCOptions type.
308
309 @param key Raw key material, length keyLength bytes.
310
311 @param keyLength Length of key material. Must be appropriate
312 for the selected operation and algorithm. Some
313 algorithms provide for varying key lengths.
314
315 @param iv Initialization vector, optional. Used by
316 block ciphers when Cipher Block Chaining (CBC)
317 mode is enabled. If present, must be the same
318 length as the selected algorithm's block size.
319 If CBC mode is selected (by the absence of the
320 kCCOptionECBMode bit in the options flags) and no
321 IV is present, a NULL (all zeroes) IV will be used.
322 This parameter is ignored if ECB mode is used or
323 if a stream cipher algorithm is selected. For sound
324 encryption, always initialize iv with random data.
325
326 @param data A pointer to caller-supplied memory from which the
327 CCCryptorRef will be created.
328
329 @param dataLength The size of the caller-supplied memory in bytes.
330
331 @param cryptorRef A (required) pointer to the returned CCCryptorRef.
332
333 @param dataUsed Optional. If present, the actual number of bytes of
334 the caller-supplied memory which was consumed by
335 creation of the CCCryptorRef is returned here. Also,
336 if the supplied memory is of insufficent size to create
337 a CCCryptorRef, kCCBufferTooSmall is returned, and
338 the minimum required buffer size is returned via this
339 parameter if present.
340
341 @result Possible error returns are kCCParamError and kCCBufferTooSmall.
342
343 @discussion The CCCryptorRef created by this function must be disposed of
344 via CCCRyptorRelease which clears sensitive data and deallocates memory
345 when the caller is finished using the CCCryptorRef.
346*/
347CCCryptorStatus CCCryptorCreateFromData(
348 CCOperation op, /* kCCEncrypt, etc. */
349 CCAlgorithm alg, /* kCCAlgorithmDES, etc. */
350 CCOptions options, /* kCCOptionPKCS7Padding, etc. */
351 const void *key, /* raw key material */
352 size_t keyLength,
353 const void *iv, /* optional initialization vector */
354 const void *data, /* caller-supplied memory */
355 size_t dataLength, /* length of data in bytes */
356 CCCryptorRef *cryptorRef, /* RETURNED */
357 size_t *dataUsed) /* optional, RETURNED */
358API_AVAILABLE(macos(10.4), ios(2.0));
359
360/*!
361 @function CCCryptorRelease
362 @abstract Free a context created by CCCryptorCreate or
363 CCCryptorCreateFromData().
364
365 @param cryptorRef The CCCryptorRef to release.
366
367 @result The only possible error return is kCCParamError resulting
368 from passing in a null CCCryptorRef.
369*/
370CCCryptorStatus CCCryptorRelease(
371 CCCryptorRef cryptorRef)
372API_AVAILABLE(macos(10.4), ios(2.0));
373
374/*!
375 @function CCCryptorUpdate
376 @abstract Process (encrypt, decrypt) some data. The result, if any,
377 is written to a caller-provided buffer.
378
379 @param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
380 CCCryptorCreateFromData().
381 @param dataIn Data to process, length dataInLength bytes.
382 @param dataInLength Length of data to process.
383 @param dataOut Result is written here. Allocated by caller.
384 Encryption and decryption can be performed
385 "in-place", with the same buffer used for
386 input and output. The in-place operation is not
387 suported for ciphers modes that work with blocks
388 of data such as CBC and ECB.
389
390 @param dataOutAvailable The size of the dataOut buffer in bytes.
391 @param dataOutMoved On successful return, the number of bytes
392 written to dataOut.
393
394 @result kCCBufferTooSmall indicates insufficent space in the dataOut
395 buffer. The caller can use
396 CCCryptorGetOutputLength() to determine the
397 required output buffer size in this case. The
398 operation can be retried; no state is lost
399 when this is returned.
400
401 @discussion This routine can be called multiple times. The caller does
402 not need to align input data lengths to block sizes; input is
403 bufferred as necessary for block ciphers.
404
405 When performing symmetric encryption with block ciphers,
406 and padding is enabled via kCCOptionPKCS7Padding, the total
407 number of bytes provided by all the calls to this function
408 when encrypting can be arbitrary (i.e., the total number
409 of bytes does not have to be block aligned). However if
410 padding is disabled, or when decrypting, the total number
411 of bytes does have to be aligned to the block size; otherwise
412 CCCryptFinal() will return kCCAlignmentError.
413
414 A general rule for the size of the output buffer which must be
415 provided by the caller is that for block ciphers, the output
416 length is never larger than the input length plus the block size.
417 For stream ciphers, the output length is always exactly the same
418 as the input length. See the discussion for
419 CCCryptorGetOutputLength() for more information on this topic.
420
421 Generally, when all data has been processed, call
422 CCCryptorFinal().
423
424 In the following cases, the CCCryptorFinal() is superfluous as
425 it will not yield any data nor return an error:
426 1. Encrypting or decrypting with a block cipher with padding
427 disabled, when the total amount of data provided to
428 CCCryptorUpdate() is an integral multiple of the block size.
429 2. Encrypting or decrypting with a stream cipher.
430 */
431CCCryptorStatus CCCryptorUpdate(
432 CCCryptorRef cryptorRef,
433 const void *dataIn,
434 size_t dataInLength,
435 void *dataOut, /* data RETURNED here */
436 size_t dataOutAvailable,
437 size_t *dataOutMoved) /* number of bytes written */
438API_AVAILABLE(macos(10.4), ios(2.0));
439
440/*!
441 @function CCCryptorFinal
442 @abstract Finish an encrypt or decrypt operation, and obtain the (possible)
443 final data output.
444
445 @param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
446 CCCryptorCreateFromData().
447 @param dataOut Result is written here. Allocated by caller.
448 @param dataOutAvailable The size of the dataOut buffer in bytes.
449 @param dataOutMoved On successful return, the number of bytes
450 written to dataOut.
451
452 @result kCCBufferTooSmall indicates insufficent space in the dataOut
453 buffer. The caller can use
454 CCCryptorGetOutputLength() to determine the
455 required output buffer size in this case. The
456 operation can be retried; no state is lost
457 when this is returned.
458 kCCAlignmentError When decrypting, or when encrypting with a
459 block cipher with padding disabled,
460 kCCAlignmentError will be returned if the total
461 number of bytes provided to CCCryptUpdate() is
462 not an integral multiple of the current
463 algorithm's block size.
464 kCCDecodeError Indicates garbled ciphertext or the
465 wrong key during decryption. This can only
466 be returned while decrypting with padding
467 enabled.
468
469 @discussion Except when kCCBufferTooSmall is returned, the CCCryptorRef
470 can no longer be used for subsequent operations unless
471 CCCryptorReset() is called on it.
472
473 It is not necessary to call CCCryptorFinal() when performing
474 symmetric encryption or decryption if padding is disabled, or
475 when using a stream cipher.
476
477 It is not necessary to call CCCryptorFinal() prior to
478 CCCryptorRelease() when aborting an operation.
479 */
480CCCryptorStatus CCCryptorFinal(
481 CCCryptorRef cryptorRef,
482 void *dataOut,
483 size_t dataOutAvailable,
484 size_t *dataOutMoved) /* number of bytes written */
485API_AVAILABLE(macos(10.4), ios(2.0));
486
487/*!
488 @function CCCryptorGetOutputLength
489 @abstract Determine output buffer size required to process a given input
490 size.
491
492 @param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
493 CCCryptorCreateFromData().
494 @param inputLength The length of data which will be provided to
495 CCCryptorUpdate().
496 @param final If false, the returned value will indicate the
497 output buffer space needed when 'inputLength'
498 bytes are provided to CCCryptorUpdate(). When
499 'final' is true, the returned value will indicate
500 the total combined buffer space needed when
501 'inputLength' bytes are provided to
502 CCCryptorUpdate() and then CCCryptorFinal() is
503 called.
504
505 @result The maximum buffer space need to perform CCCryptorUpdate() and
506 optionally CCCryptorFinal().
507
508 @discussion Some general rules apply that allow clients of this module to
509 know a priori how much output buffer space will be required
510 in a given situation. For stream ciphers, the output size is
511 always equal to the input size, and CCCryptorFinal() never
512 produces any data. For block ciphers, the output size will
513 always be less than or equal to the input size plus the size
514 of one block. For block ciphers, if the input size provided
515 to each call to CCCryptorUpdate() is is an integral multiple
516 of the block size, then the output size for each call to
517 CCCryptorUpdate() is less than or equal to the input size
518 for that call to CCCryptorUpdate(). CCCryptorFinal() only
519 produces output when using a block cipher with padding enabled.
520*/
521size_t CCCryptorGetOutputLength(
522 CCCryptorRef cryptorRef,
523 size_t inputLength,
524 bool final)
525API_AVAILABLE(macos(10.4), ios(2.0));
526
527
528/*!
529 @function CCCryptorReset
530 @abstract Reinitializes an existing CCCryptorRef with a (possibly)
531 new initialization vector. The CCCryptorRef's key is
532 unchanged. Use only for CBC and CTR modes.
533
534 @param cryptorRef A CCCryptorRef created via CCCryptorCreate() or
535 CCCryptorCreateFromData().
536 @param iv Optional initialization vector; if present, must
537 be the same size as the current algorithm's block
538 size. For sound encryption, always initialize iv with
539 random data.
540
541 @result The only possible errors are kCCParamError and
542 kCCUnimplemented. On macOS 10.13, iOS 11, watchOS 4 and tvOS 11 returns kCCUnimplemented
543 for modes other than CBC. On prior SDKs, returns kCCSuccess to preserve compatibility
544
545 @discussion This can be called on a CCCryptorRef with data pending (i.e.
546 in a padded mode operation before CCCryptFinal is called);
547 however any pending data will be lost in that case.
548*/
549CCCryptorStatus CCCryptorReset(
550 CCCryptorRef cryptorRef,
551 const void *iv)
552 API_AVAILABLE(macos(10.4), ios(2.0));
553
554
555/*!
556 @function CCCrypt
557 @abstract Stateless, one-shot encrypt or decrypt operation.
558 This basically performs a sequence of CCCrytorCreate(),
559 CCCryptorUpdate(), CCCryptorFinal(), and CCCryptorRelease().
560
561 @param alg Defines the encryption algorithm.
562
563
564 @param op Defines the basic operation: kCCEncrypt or
565 kCCDecrypt.
566
567 @param options A word of flags defining options. See discussion
568 for the CCOptions type.
569
570 @param key Raw key material, length keyLength bytes.
571
572 @param keyLength Length of key material. Must be appropriate
573 for the select algorithm. Some algorithms may
574 provide for varying key lengths.
575
576 @param iv Initialization vector, optional. Used for
577 Cipher Block Chaining (CBC) mode. If present,
578 must be the same length as the selected
579 algorithm's block size. If CBC mode is
580 selected (by the absence of any mode bits in
581 the options flags) and no IV is present, a
582 NULL (all zeroes) IV will be used. This is
583 ignored if ECB mode is used or if a stream
584 cipher algorithm is selected. For sound encryption,
585 always initialize IV with random data.
586
587 @param dataIn Data to encrypt or decrypt, length dataInLength
588 bytes.
589
590 @param dataInLength Length of data to encrypt or decrypt.
591
592 @param dataOut Result is written here. Allocated by caller.
593 Encryption and decryption can be performed
594 "in-place", with the same buffer used for
595 input and output.
596
597 @param dataOutAvailable The size of the dataOut buffer in bytes.
598
599 @param dataOutMoved On successful return, the number of bytes
600 written to dataOut. If kCCBufferTooSmall is
601 returned as a result of insufficient buffer
602 space being provided, the required buffer space
603 is returned here.
604
605 @result kCCBufferTooSmall indicates insufficent space in the dataOut
606 buffer. In this case, the *dataOutMoved
607 parameter will indicate the size of the buffer
608 needed to complete the operation. The
609 operation can be retried with minimal runtime
610 penalty.
611 kCCAlignmentError indicates that dataInLength was not properly
612 aligned. This can only be returned for block
613 ciphers, and then only when decrypting or when
614 encrypting with block with padding disabled.
615 kCCDecodeError Indicates improperly formatted ciphertext or
616 a "wrong key" error; occurs only during decrypt
617 operations.
618 */
619
620CCCryptorStatus CCCrypt(
621 CCOperation op, /* kCCEncrypt, etc. */
622 CCAlgorithm alg, /* kCCAlgorithmAES128, etc. */
623 CCOptions options, /* kCCOptionPKCS7Padding, etc. */
624 const void *key,
625 size_t keyLength,
626 const void *iv, /* optional initialization vector */
627 const void *dataIn, /* optional per op and alg */
628 size_t dataInLength,
629 void *dataOut, /* data RETURNED here */
630 size_t dataOutAvailable,
631 size_t *dataOutMoved)
632 API_AVAILABLE(macos(10.4), ios(2.0));
633
634
635/*!
636 @enum Cipher Modes
637 @discussion These are the selections available for modes of operation for
638 use with block ciphers. If RC4 is selected as the cipher (a stream
639 cipher) the only correct mode is kCCModeRC4.
640
641 @constant kCCModeECB - Electronic Code Book Mode.
642 @constant kCCModeCBC - Cipher Block Chaining Mode.
643 @constant kCCModeCFB - Cipher Feedback Mode.
644 @constant kCCModeOFB - Output Feedback Mode.
645 @constant kCCModeRC4 - RC4 as a streaming cipher is handled internally as a mode.
646 @constant kCCModeCFB8 - Cipher Feedback Mode producing 8 bits per round.
647*/
648
649
650enum {
651 kCCModeECB = 1,
652 kCCModeCBC = 2,
653 kCCModeCFB = 3,
654 kCCModeCTR = 4,
655 kCCModeOFB = 7,
656 kCCModeRC4 = 9,
657 kCCModeCFB8 = 10,
658};
659typedef uint32_t CCMode;
660
661/*!
662 @enum Padding for Block Ciphers
663 @discussion These are the padding options available for block modes.
664
665 @constant ccNoPadding - No padding.
666 @constant ccPKCS7Padding - PKCS7 Padding.
667*/
668
669enum {
670 ccNoPadding = 0,
671 ccPKCS7Padding = 1,
672};
673typedef uint32_t CCPadding;
674
675/*!
676 @enum Mode options - Not currently in use.
677
678 @discussion Values used to specify options for modes. This was used for counter
679 mode operations in 10.8, now only Big Endian mode is supported.
680
681 @constant kCCModeOptionCTR_BE - CTR Mode Big Endian.
682*/
683
684enum {
685 kCCModeOptionCTR_BE = 2
686};
687
688typedef uint32_t CCModeOptions;
689
690/*!
691 @function CCCryptorCreateWithMode
692 @abstract Create a cryptographic context.
693
694 @param op Defines the basic operation: kCCEncrypt or
695 kCCDecrypt.
696
697 @param mode Specifies the cipher mode to use for operations.
698
699 @param alg Defines the algorithm.
700
701 @param padding Specifies the padding to use.
702
703 @param iv Initialization vector, optional. Used by
704 block ciphers with the following modes:
705
706 Cipher Block Chaining (CBC)
707 Cipher Feedback (CFB and CFB8)
708 Output Feedback (OFB)
709 Counter (CTR)
710
711 If present, must be the same length as the selected
712 algorithm's block size. If no IV is present, a NULL
713 (all zeroes) IV will be used. For sound encryption,
714 always initialize iv with random data.
715
716 This parameter is ignored if ECB mode is used or
717 if a stream cipher algorithm is selected.
718
719 @param key Raw key material, length keyLength bytes.
720
721 @param keyLength Length of key material. Must be appropriate
722 for the selected operation and algorithm. Some
723 algorithms provide for varying key lengths.
724
725 @param tweak Raw key material, length keyLength bytes. Used for the
726 tweak key in XEX-based Tweaked CodeBook (XTS) mode.
727
728 @param tweakLength Length of tweak key material. Must be appropriate
729 for the selected operation and algorithm. Some
730 algorithms provide for varying key lengths. For XTS
731 this is the same length as the encryption key.
732
733 @param numRounds The number of rounds of the cipher to use. 0 uses the default.
734
735 @param options A word of flags defining options. See discussion
736 for the CCModeOptions type.
737
738 @param cryptorRef A (required) pointer to the returned CCCryptorRef.
739
740 @result Possible error returns are kCCParamError and kCCMemoryFailure.
741 */
742
743
744CCCryptorStatus CCCryptorCreateWithMode(
745 CCOperation op, /* kCCEncrypt, kCCDecrypt */
746 CCMode mode,
747 CCAlgorithm alg,
748 CCPadding padding,
749 const void *iv, /* optional initialization vector */
750 const void *key, /* raw key material */
751 size_t keyLength,
752 const void *tweak, /* raw tweak material */
753 size_t tweakLength,
754 int numRounds, /* 0 == default */
755 CCModeOptions options,
756 CCCryptorRef *cryptorRef) /* RETURNED */
757API_AVAILABLE(macos(10.7), ios(5.0));
758
759#ifdef __cplusplus
760}
761#endif
762
763#endif /* _CC_COMMON_CRYPTOR_ */