AWS SDK for C++  1.8.76
AWS SDK for C++
CommonCryptorSPI.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 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 #ifndef _CC_CryptorSPI_H_
25 #define _CC_CryptorSPI_H_
26 
27 #include <sys/types.h>
28 #include <stdint.h>
29 
30 #include <string.h>
31 #include <limits.h>
32 #include <stdlib.h>
33 
34 #include <os/availability.h>
35 
36 #include <CommonCrypto/CommonCryptoError.h>
37 #include <CommonCrypto/CommonCryptor.h>
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 #if defined(_WIN32)
44  int timingsafe_bcmp(const void *b1, const void *b2, size_t n);
45 #endif
46 /*
47  This is an SPI header. It includes some work in progress implementation notes that
48  will be removed when this is promoted to an API set.
49 */
50 
51 /*
52  Private Ciphers
53  */
54 
55 /* Lion SPI name for no padding. Defining for compatibility. Is now
56  ccNoPadding in CommonCryptor.h
57  */
58 
59 enum {
61 };
62 
63 
64 enum {
67 };
68 
69 /*
70  Private Modes
71  */
72 enum {
73  kCCModeGCM = 11,
74  kCCModeCCM = 12,
75 };
76 
77 /*
78  Private Paddings
79  */
80 enum {
81  ccCBCCTS1 = 10,
82  ccCBCCTS2 = 11,
83  ccCBCCTS3 = 12,
84 };
85 
86 /*
87  Private Cryptor direction (op)
88  */
89 enum {
90  kCCBoth = 3,
91 };
92 
93 
94 
95 
96 /*
97  Supports a mode call of
98  int mode_setup(int cipher, const unsigned char *IV, const unsigned char *key, int keylen,
99  const unsigned char *tweak, int tweaklen, int num_rounds, int options, mode_context *ctx);
100 */
101 
102 /* User supplied space for the CryptorRef */
103 
104 CCCryptorStatus CCCryptorCreateFromDataWithMode(
105  CCOperation op, /* kCCEncrypt, kCCEncrypt, kCCBoth (default for BlockMode) */
106  CCMode mode,
107  CCAlgorithm alg,
108  CCPadding padding,
109  const void *iv, /* optional initialization vector */
110  const void *key, /* raw key material */
111  size_t keyLength,
112  const void *tweak, /* raw tweak material */
113  size_t tweakLength,
114  int numRounds,
115  CCModeOptions options,
116  const void *data, /* caller-supplied memory */
117  size_t dataLength, /* length of data in bytes */
118  CCCryptorRef *cryptorRef, /* RETURNED */
119  size_t *dataUsed) /* optional, RETURNED */
120 API_AVAILABLE(macos(10.7), ios(5.0));
121 
122 
123 /*
124  Assuming we can use existing CCCryptorCreateFromData for all modes serviced by these:
125  int mode_encrypt(const unsigned char *pt, unsigned char *ct, unsigned long len, mode_context *ctx);
126  int mode_decrypt(const unsigned char *ct, unsigned char *pt, unsigned long len, mode_context *ctx);
127 */
128 
129 /*
130  Block mode encrypt and decrypt interfaces for IV tweaked blocks (XTS and CBC)
131 
132  int mode_encrypt_tweaked(const unsigned char *pt, unsigned long len, unsigned char *ct, const unsigned char *tweak, mode_context *ctx);
133  int mode_decrypt_tweaked(const unsigned char *ct, unsigned long len, unsigned char *pt, const unsigned char *tweak, mode_context *ctx);
134 */
135 
136 CCCryptorStatus CCCryptorEncryptDataBlock(
137  CCCryptorRef cryptorRef,
138  const void *iv,
139  const void *dataIn,
140  size_t dataInLength,
141  void *dataOut)
142 API_AVAILABLE(macos(10.7), ios(5.0));
143 
144 
145 CCCryptorStatus CCCryptorDecryptDataBlock(
146  CCCryptorRef cryptorRef,
147  const void *iv,
148  const void *dataIn,
149  size_t dataInLength,
150  void *dataOut)
151 API_AVAILABLE(macos(10.7), ios(5.0));
152 
153 
165 CCCryptorStatus CCCryptorReset_binary_compatibility(CCCryptorRef cryptorRef, const void *iv)
166  API_DEPRECATED_WITH_REPLACEMENT("CCCryptorReset", macos(10.4, 10.13), ios(2.0, 11.0));
167 
168 /*
169  Assuming we can use the existing CCCryptorRelease() interface for
170  int mode_done(mode_context *ctx);
171 */
172 
173 /*
174  Not surfacing these other than with CCCryptorReset()
175 
176  int mode_setIV(const unsigned char *IV, unsigned long len, mode_context *ctx);
177  int mode_getIV(const unsigned char *IV, unsigned long *len, mode_context *ctx);
178 */
179 
180 /*
181  * returns a cipher blocksize length iv in the provided iv buffer.
182  */
183 
184 CCCryptorStatus
185 CCCryptorGetIV(CCCryptorRef cryptorRef, void *iv)
186 API_AVAILABLE(macos(10.7), ios(5.0));
187 
188 /*
189  GCM Support Interfaces
190 
191  Use CCCryptorCreateWithMode() with the kCCModeGCM selector to initialize
192  a CryptoRef. Only kCCAlgorithmAES128 can be used with GCM and these
193  functions. IV Setting etc will be ignored from CCCryptorCreateWithMode().
194  Use the CCCryptorGCMAddIV() routine below for IV setup.
195 */
196 
197 /*
198  Deprecated. Use CCCryptorGCMSetIV() instead.
199  This adds the initial vector octets from iv of length ivLen to the GCM
200  CCCryptorRef. You can call this function as many times as required to
201  process the entire IV.
202 */
203 
204 CCCryptorStatus
205 CCCryptorGCMAddIV(CCCryptorRef cryptorRef,
206  const void *iv, size_t ivLen)
207 API_DEPRECATED_WITH_REPLACEMENT("CCCryptorGCMSetIV", macos(10.8, 10.13), ios(5.0, 11.0));
208 
209 
210 /*
211  This adds the initial vector octets from iv of length ivLen to the GCM
212  CCCryptorRef. The input iv cannot be NULL and ivLen must be between 12
213  to 16 bytes inclusive. CCRandomGenerateBytes() can be used to generate random IVs
214 */
215 
216 CCCryptorStatus
217 CCCryptorGCMSetIV(CCCryptorRef cryptorRef,
218  const void *iv, size_t ivLen)
219 API_AVAILABLE(macos(10.13), ios(11.0));
220 /*
221  Additional Authentication Data
222  After the entire IV has been processed, the additional authentication
223  data can be processed. Unlike the IV, a packet/session does not require
224  additional authentication data (AAD) for security. The AAD is meant to
225  be used as side channel data you want to be authenticated with the packet.
226  Note: once you begin adding AAD to the GCM CCCryptorRef you cannot return
227  to adding IV data until the state has been reset.
228 */
229 
230 CCCryptorStatus
231 CCCryptorGCMAddAAD(CCCryptorRef cryptorRef,
232  const void *aData,
233  size_t aDataLen)
234 API_AVAILABLE(macos(10.8), ios(6.0));
235 
236 
237 // This is for old iOS5 clients
238 CCCryptorStatus
239 CCCryptorGCMAddADD(CCCryptorRef cryptorRef,
240  const void *aData,
241  size_t aDataLen)
242 API_AVAILABLE(macos(10.8), ios(5.0));
243 
244 
245 CCCryptorStatus CCCryptorGCMEncrypt(
246  CCCryptorRef cryptorRef,
247  const void *dataIn,
248  size_t dataInLength,
249  void *dataOut)
250 API_AVAILABLE(macos(10.8), ios(5.0));
251 
252 
253 CCCryptorStatus CCCryptorGCMDecrypt(
254  CCCryptorRef cryptorRef,
255  const void *dataIn,
256  size_t dataInLength,
257  void *dataOut)
258 API_AVAILABLE(macos(10.8), ios(5.0));
259 
260 /*
261  This finalizes the GCM state gcm and stores the tag in tag of length
262  taglen octets.
263 
264  The tag must be verified by comparing the computed and expected values
265  using timingsafe_bcmp. Other comparison functions (e.g. memcmp)
266  must not be used as they may be vulnerable to practical timing attacks,
267  leading to tag forgery.
268 
269 */
270 
271 CCCryptorStatus CCCryptorGCMFinal(
272  CCCryptorRef cryptorRef,
273  void *tagOut,
274  size_t *tagLength)
275 API_DEPRECATED_WITH_REPLACEMENT("CCCryptorGCMFinalize", macos(10.8, 10.13), ios(5.0, 11.0));
276 
277 /*
278  This finalizes the GCM state gcm.
279 
280  On encryption, the computed tag is returned in tagOut.
281 
282  On decryption, the provided tag is securely compared to the expected tag, and
283  error is returned if the tags do not match. The tag buffer content is not modified on decryption.
284  is not updated on decryption.
285 */
286 CCCryptorStatus CCCryptorGCMFinalize(
287  CCCryptorRef cryptorRef,
288  void *tag,
289  size_t tagLength)
290 API_AVAILABLE(macos(10.13), ios(11.0));
291 
292 /*
293  This will reset the GCM CCCryptorRef to the state that CCCryptorCreateWithMode()
294  left it. The user would then call CCCryptorGCMAddIV(), CCCryptorGCMAddAAD(), etc.
295 */
296 
297 CCCryptorStatus CCCryptorGCMReset(
298  CCCryptorRef cryptorRef)
299 API_AVAILABLE(macos(10.8), ios(5.0));
300 
301 /*
302  Deprecated. Use CCCryptorGCMOneshotEncrypt() or CCCryptorGCMOneshotDecrypt() instead.
303 
304  This will initialize the GCM state with the given key, IV and AAD value
305  then proceed to encrypt or decrypt the message text and store the final
306  message tag. The definition of the variables is the same as it is for all
307  the manual functions. If you are processing many packets under the same
308  key you shouldn't use this function as it invokes the pre-computation
309  with each call.
310 
311  The tag must be verified by comparing the computed and expected values
312  using timingsafe_bcmp. Other comparison functions (e.g. memcmp)
313  must not be used as they may be vulnerable to practical timing attacks,
314  leading to tag forgery.
315 */
316 
317 CCCryptorStatus CCCryptorGCM(
318  CCOperation op, /* kCCEncrypt, kCCDecrypt */
319  CCAlgorithm alg,
320  const void *key, /* raw key material */
321  size_t keyLength,
322  const void *iv,
323  size_t ivLen,
324  const void *aData,
325  size_t aDataLen,
326  const void *dataIn,
327  size_t dataInLength,
328  void *dataOut,
329  void *tagOut,
330  size_t *tagLength)
331 API_DEPRECATED_WITH_REPLACEMENT("CCCryptorGCMOneshotEncrypt or CCCryptorGCMOneshotDecrypt", macos(10.8, 10.13), ios(6.0, 11.0));
332 
364 CCCryptorStatus CCCryptorGCMOneshotEncrypt(CCAlgorithm alg, const void *key, size_t keyLength, /* raw key material */
365  const void *iv, size_t ivLength,
366  const void *aData, size_t aDataLength,
367  const void *dataIn, size_t dataInLength,
368  void *cipherOut,
369  void *tagOut, size_t tagLength) __attribute__((__warn_unused_result__))
370 API_AVAILABLE(macos(10.13), ios(11.0));
371 
379 CCCryptorStatus CCCryptorGCMOneshotDecrypt(CCAlgorithm alg, const void *key, size_t keyLength,
380  const void *iv, size_t ivLen,
381  const void *aData, size_t aDataLen,
382  const void *dataIn, size_t dataInLength,
383  void *dataOut,
384  const void *tagIn, size_t tagLength) __attribute__((__warn_unused_result__))
385  API_AVAILABLE(macos(10.13), ios(11.0));
386 
387 void CC_RC4_set_key(void *ctx, int len, const unsigned char *data)
388 API_AVAILABLE(macos(10.4), ios(5.0));
389 
390 void CC_RC4(void *ctx, unsigned long len, const unsigned char *indata,
391  unsigned char *outdata)
392 API_AVAILABLE(macos(10.4), ios(5.0));
393 
394 /*
395 GCM interface can then be easily bolt on the rest of standard CCCryptor interface; typically following sequence can be used:
396 
397 CCCryptorCreateWithMode(mode = kCCModeGCM)
398 0..Nx: CCCryptorAddParameter(kCCParameterIV, iv)
399 0..Nx: CCCryptorAddParameter(kCCParameterAuthData, data)
400 0..Nx: CCCryptorUpdate(inData, outData)
401 0..1: CCCryptorFinal(outData)
402 0..1: CCCryptorGetParameter(kCCParameterAuthTag, tag)
403 CCCryptorRelease()
404 
405 */
406 
407 enum {
408  /*
409  Initialization vector - cryptor input parameter, typically
410  needs to have the same length as block size, but in some cases
411  (GCM) it can be arbitrarily long and even might be called
412  multiple times.
413  */
415 
416  /*
417  Authentication data - cryptor input parameter, input for
418  authenticating encryption modes like GCM. If supported, can
419  be called multiple times before encryption starts.
420  */
422 
423  /*
424  Mac Size - cryptor input parameter, input for
425  authenticating encryption modes like CCM. Specifies the size of
426  the AuthTag the algorithm is expected to produce.
427  */
429 
430  /*
431  Data Size - cryptor input parameter, input for
432  authenticating encryption modes like CCM. Specifies the amount of
433  data the algorithm is expected to process.
434  */
436 
437  /*
438  Authentication tag - cryptor output parameter, output from
439  authenticating encryption modes like GCM. If supported,
440  should be retrieved after the encryption finishes.
441  */
443 };
444 typedef uint32_t CCParameter;
445 
446 /*
447  Sets or adds some other cryptor input parameter. According to the
448  cryptor type and state, parameter can be either accepted or
449  refused with kCCUnimplemented (when given parameter is not
450  supported for this type of cryptor at all) or kCCParamError (bad
451  data length or format).
452 */
453 
454 CCCryptorStatus CCCryptorAddParameter(
455  CCCryptorRef cryptorRef,
456  CCParameter parameter,
457  const void *data,
458  size_t dataSize);
459 
460 
461 /*
462  Gets value of output cryptor parameter. According to the cryptor
463  type state, the request can be either accepted or refused with
464  kCCUnimplemented (when given parameteris not supported for this
465  type of cryptor) or kCCBufferTooSmall (in this case, *dataSize
466  argument is set to the requested size of data).
467 */
468 
469 CCCryptorStatus CCCryptorGetParameter(
470  CCCryptorRef cryptorRef,
471  CCParameter parameter,
472  void *data,
473  size_t *dataSize);
474 
475 
476 #ifdef __cplusplus
477 }
478 #endif
479 
480 #endif /* _CC_CryptorSPI_H_ */
CCCryptorStatus CCCryptorGCM(CCOperation op, CCAlgorithm alg, const void *key, size_t keyLength, const void *iv, size_t ivLen, const void *aData, size_t aDataLen, const void *dataIn, size_t dataInLength, void *dataOut, void *tagOut, size_t *tagLength) API_DEPRECATED_WITH_REPLACEMENT("CCCryptorGCMOneshotEncrypt or CCCryptorGCMOneshotDecrypt"
uint32_t CCParameter
CCCryptorStatus CCCryptorGCMFinal(CCCryptorRef cryptorRef, void *tagOut, size_t *tagLength) API_DEPRECATED_WITH_REPLACEMENT("CCCryptorGCMFinalize"
void CC_RC4(void *ctx, unsigned long len, const unsigned char *indata, unsigned char *outdata) API_AVAILABLE(macos(10.4)
CCCryptorStatus CCCryptorGCMDecrypt(CCCryptorRef cryptorRef, const void *dataIn, size_t dataInLength, void *dataOut) API_AVAILABLE(macos(10.8)
CCCryptorStatus CCCryptorCreateFromDataWithMode(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, const void *data, size_t dataLength, CCCryptorRef *cryptorRef, size_t *dataUsed) API_AVAILABLE(macos(10.7)
CCCryptorStatus CCCryptorGetIV(CCCryptorRef cryptorRef, void *iv) API_AVAILABLE(macos(10.7)
CCCryptorStatus CCCryptorGCMAddADD(CCCryptorRef cryptorRef, const void *aData, size_t aDataLen) API_AVAILABLE(macos(10.8)
CCCryptorStatus macos(10.4, 10.13)
CCCryptorStatus CCCryptorGCMSetIV(CCCryptorRef cryptorRef, const void *iv, size_t ivLen) API_AVAILABLE(macos(10.13)
CCCryptorStatus CCCryptorGCMReset(CCCryptorRef cryptorRef) API_AVAILABLE(macos(10.8)
CCCryptorStatus ios(5.0))
CCCryptorStatus CCCryptorGetParameter(CCCryptorRef cryptorRef, CCParameter parameter, void *data, size_t *dataSize)
CCCryptorStatus CCCryptorDecryptDataBlock(CCCryptorRef cryptorRef, const void *iv, const void *dataIn, size_t dataInLength, void *dataOut) API_AVAILABLE(macos(10.7)
CCCryptorStatus CCCryptorGCMEncrypt(CCCryptorRef cryptorRef, const void *dataIn, size_t dataInLength, void *dataOut) API_AVAILABLE(macos(10.8)
CCCryptorStatus CCCryptorGCMFinalize(CCCryptorRef cryptorRef, void *tag, size_t tagLength) API_AVAILABLE(macos(10.13)
CCCryptorStatus CCCryptorGCMOneshotDecrypt(CCAlgorithm alg, const void *key, size_t keyLength, const void *iv, size_t ivLen, const void *aData, size_t aDataLen, const void *dataIn, size_t dataInLength, void *dataOut, const void *tagIn, size_t tagLength) __attribute__((__warn_unused_result__)) API_AVAILABLE(macos(10.13)
CCCryptorStatus CCCryptorReset_binary_compatibility(CCCryptorRef cryptorRef, const void *iv) API_DEPRECATED_WITH_REPLACEMENT("CCCryptorReset"
void CC_RC4_set_key(void *ctx, int len, const unsigned char *data) API_AVAILABLE(macos(10.4)
CCCryptorStatus CCCryptorGCMAddAAD(CCCryptorRef cryptorRef, const void *aData, size_t aDataLen) API_AVAILABLE(macos(10.8)
CCCryptorStatus CCCryptorEncryptDataBlock(CCCryptorRef cryptorRef, const void *iv, const void *dataIn, size_t dataInLength, void *dataOut) API_AVAILABLE(macos(10.7)
CCCryptorStatus CCCryptorGCMOneshotEncrypt(CCAlgorithm alg, const void *key, size_t keyLength, const void *iv, size_t ivLength, const void *aData, size_t aDataLength, const void *dataIn, size_t dataInLength, void *cipherOut, void *tagOut, size_t tagLength) __attribute__((__warn_unused_result__)) API_AVAILABLE(macos(10.13)
CCCryptorStatus CCCryptorAddParameter(CCCryptorRef cryptorRef, CCParameter parameter, const void *data, size_t dataSize)
CCCryptorStatus CCCryptorGCMAddIV(CCCryptorRef cryptorRef, const void *iv, size_t ivLen) API_DEPRECATED_WITH_REPLACEMENT("CCCryptorGCMSetIV"