···11+/*
22+ * Copyright (c) 2010 Apple Inc. All Rights Reserved.
33+ *
44+ * @APPLE_LICENSE_HEADER_START@
55+ *
66+ * This file contains Original Code and/or Modifications of Original Code
77+ * as defined in and that are subject to the Apple Public Source License
88+ * Version 2.0 (the 'License'). You may not use this file except in
99+ * compliance with the License. Please obtain a copy of the License at
1010+ * http://www.opensource.apple.com/apsl/ and read it before using this
1111+ * file.
1212+ *
1313+ * The Original Code and all software distributed under the License are
1414+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1515+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1616+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
1717+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
1818+ * Please see the License for the specific language governing rights and
1919+ * limitations under the License.
2020+ *
2121+ * @APPLE_LICENSE_HEADER_END@
2222+ */
2323+2424+#ifndef _CC_CryptorSPI_H_
2525+#define _CC_CryptorSPI_H_
2626+2727+#include <sys/types.h>
2828+#include <sys/param.h>
2929+#include <stdint.h>
3030+3131+#include <string.h>
3232+#include <limits.h>
3333+#include <stdlib.h>
3434+#include <Availability.h>
3535+3636+#ifdef __cplusplus
3737+extern "C" {
3838+#endif
3939+4040+/*
4141+ This is an SPI header. It includes some work in progress implementation notes that
4242+ will be removed when this is promoted to an API set.
4343+*/
4444+4545+/*
4646+ Cipher Modes
4747+*/
4848+4949+enum {
5050+ kCCModeECB = 1,
5151+ kCCModeCBC = 2,
5252+ kCCModeCFB = 3,
5353+ kCCModeCTR = 4,
5454+ kCCModeF8 = 5, // Unimplemented for now (not included)
5555+ kCCModeLRW = 6, // Unimplemented for now (not included)
5656+ kCCModeOFB = 7,
5757+ kCCModeXTS = 8,
5858+ kCCModeRC4 = 9, // RC4 as a streaming cipher is handled internally as a mode.
5959+ kCCModeCFB8 = 10,
6060+};
6161+typedef uint32_t CCMode;
6262+6363+/*
6464+ Padding for block ciphers
6565+*/
6666+6767+enum {
6868+ ccDefaultPadding = 0,
6969+ ccPKCS7Padding = 1,
7070+ ccANSIx923Padding = 2, // Unimplemented for now (not included)
7171+ ccISO10126Padding = 3, // Unimplemented for now (not included)
7272+};
7373+typedef uint32_t CCPadding;
7474+7575+/*
7676+ Mode options - so far only used for CTR mode
7777+*/
7878+7979+enum {
8080+ kCCModeOptionCTR_LE = 0x0001, // CTR Mode Little Endian
8181+ kCCModeOptionCTR_BE = 0x0002 // CTR Mode Big Endian
8282+};
8383+8484+typedef uint32_t CCModeOptions;
8585+8686+/*
8787+ Supports a mode call of
8888+ int mode_setup(int cipher, const unsigned char *IV, const unsigned char *key, int keylen,
8989+ const unsigned char *tweak, int tweaklen, int num_rounds, int options, mode_context *ctx);
9090+*/
9191+9292+/* User supplied space for the CryptorRef */
9393+9494+CCCryptorStatus CCCryptorCreateFromDataWithMode(
9595+ CCOperation op, /* kCCEncrypt, kCCEncrypt, kCCBoth (default for BlockMode) */
9696+ CCMode mode,
9797+ CCAlgorithm alg,
9898+ CCPadding padding,
9999+ const void *iv, /* optional initialization vector */
100100+ const void *key, /* raw key material */
101101+ size_t keyLength,
102102+ const void *tweak, /* raw tweak material */
103103+ size_t tweakLength,
104104+ int numRounds,
105105+ CCModeOptions options,
106106+ const void *data, /* caller-supplied memory */
107107+ size_t dataLength, /* length of data in bytes */
108108+ CCCryptorRef *cryptorRef, /* RETURNED */
109109+ size_t *dataUsed) /* optional, RETURNED */
110110+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
111111+112112+/* This version mallocs the CCCryptorRef */
113113+114114+CCCryptorStatus CCCryptorCreateWithMode(
115115+ CCOperation op, /* kCCEncrypt, kCCEncrypt, kCCBoth (default for BlockMode) */
116116+ CCMode mode,
117117+ CCAlgorithm alg,
118118+ CCPadding padding,
119119+ const void *iv, /* optional initialization vector */
120120+ const void *key, /* raw key material */
121121+ size_t keyLength,
122122+ const void *tweak, /* raw tweak material */
123123+ size_t tweakLength,
124124+ int numRounds, /* 0 == default */
125125+ CCModeOptions options,
126126+ CCCryptorRef *cryptorRef) /* RETURNED */
127127+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
128128+129129+/*
130130+ Assuming we can use existing CCCryptorCreateFromData for all modes serviced by these:
131131+ int mode_encrypt(const unsigned char *pt, unsigned char *ct, unsigned long len, mode_context *ctx);
132132+ int mode_decrypt(const unsigned char *ct, unsigned char *pt, unsigned long len, mode_context *ctx);
133133+*/
134134+135135+/*
136136+ Block mode encrypt and decrypt interfaces for IV tweaked blocks (XTS and CBC)
137137+138138+ int mode_encrypt_tweaked(const unsigned char *pt, unsigned long len, unsigned char *ct, const unsigned char *tweak, mode_context *ctx);
139139+ int mode_decrypt_tweaked(const unsigned char *ct, unsigned long len, unsigned char *pt, const unsigned char *tweak, mode_context *ctx);
140140+*/
141141+142142+CCCryptorStatus CCCryptorEncryptDataBlock(
143143+ CCCryptorRef cryptorRef,
144144+ const void *iv,
145145+ const void *dataIn,
146146+ size_t dataInLength,
147147+ void *dataOut)
148148+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
149149+150150+151151+CCCryptorStatus CCCryptorDecryptDataBlock(
152152+ CCCryptorRef cryptorRef,
153153+ const void *iv,
154154+ const void *dataIn,
155155+ size_t dataInLength,
156156+ void *dataOut)
157157+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
158158+159159+/*
160160+ Assuming we can use the existing CCCryptorRelease() interface for
161161+ int mode_done(mode_context *ctx);
162162+*/
163163+164164+/*
165165+ Not surfacing these other than with CCCryptorReset()
166166+167167+ int mode_setiv(const unsigned char *IV, unsigned long len, mode_context *ctx);
168168+ int mode_getiv(const unsigned char *IV, unsigned long *len, mode_context *ctx);
169169+*/
170170+171171+/*
172172+ DES key utilities
173173+*/
174174+175175+CCCryptorStatus CCDesIsWeakKey(
176176+ void *key,
177177+ size_t Length)
178178+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
179179+180180+void CCDesSetOddParity(
181181+ void *key,
182182+ size_t Length)
183183+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
184184+185185+uint32_t CCDesCBCCksum(void *input, void *output,
186186+ size_t length, void *key, size_t keylen,
187187+ void *ivec)
188188+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
189189+190190+191191+192192+#ifdef __cplusplus
193193+}
194194+#endif
195195+196196+#endif /* _CC_CryptorSPI_H_ */
+58
src/CommonCrypto/CommonCrypto/CommonRandom.h
···11+/*
22+ * Copyright (c) 2014 Apple Inc. All Rights Reserved.
33+ *
44+ * @APPLE_LICENSE_HEADER_START@
55+ *
66+ * This file contains Original Code and/or Modifications of Original Code
77+ * as defined in and that are subject to the Apple Public Source License
88+ * Version 2.0 (the 'License'). You may not use this file except in
99+ * compliance with the License. Please obtain a copy of the License at
1010+ * http://www.opensource.apple.com/apsl/ and read it before using this
1111+ * file.
1212+ *
1313+ * The Original Code and all software distributed under the License are
1414+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1515+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1616+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
1717+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
1818+ * Please see the License for the specific language governing rights and
1919+ * limitations under the License.
2020+ *
2121+ * @APPLE_LICENSE_HEADER_END@
2222+ */
2323+2424+//
2525+// CommonRandom.h
2626+// CommonCrypto
2727+2828+#ifndef CommonCrypto_CommonRandom_h
2929+#define CommonCrypto_CommonRandom_h
3030+3131+#if defined(__cplusplus)
3232+extern "C" {
3333+#endif
3434+3535+typedef CCCryptorStatus CCRNGStatus;
3636+3737+/*!
3838+ @function CCRandomGenerateBytes
3939+4040+ @abstract Return random bytes in a buffer allocated by the caller.
4141+4242+ @discussion The PRNG returns cryptographically strong random
4343+ bits suitable for use as cryptographic keys, IVs, nonces etc.
4444+4545+ @param bytes Pointer to the return buffer.
4646+ @param count Number of random bytes to return.
4747+4848+ @result Return kCCSuccess on success.
4949+ */
5050+5151+CCRNGStatus CCRandomGenerateBytes(void *bytes, size_t count)
5252+__OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_8_0);
5353+5454+#if defined(__cplusplus)
5555+}
5656+#endif
5757+5858+#endif
+234
src/CommonCrypto/CommonCrypto/CommonRandomSPI.h
···11+#ifndef COMMONRANDOM_H
22+#define COMMONRANDOM_H 1
33+44+/*
55+ * CommonRandom.h
66+ *
77+ * Copyright � 2010-2011 by Apple, Inc. All rights reserved.
88+ *
99+ * @APPLE_LICENSE_HEADER_START@
1010+ *
1111+ * This file contains Original Code and/or Modifications of Original Code
1212+ * as defined in and that are subject to the Apple Public Source License
1313+ * Version 2.0 (the 'License'). You may not use this file except in
1414+ * compliance with the License. Please obtain a copy of the License at
1515+ * http://www.opensource.apple.com/apsl/ and read it before using this
1616+ * file.
1717+ *
1818+ * The Original Code and all software distributed under the License are
1919+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
2020+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
2121+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2222+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
2323+ * Please see the License for the specific language governing rights and
2424+ * limitations under the License.
2525+ *
2626+ * @APPLE_LICENSE_HEADER_END@
2727+ *
2828+ */
2929+3030+#include <dispatch/dispatch.h>
3131+#include <dispatch/queue.h>
3232+#include <Availability.h>
3333+#include <stdint.h>
3434+#include <sys/types.h>
3535+#include <CommonCrypto/CommonCryptor.h>
3636+3737+/*!
3838+3939+ @header CommonRNG.h
4040+ @abstract An interface to a system random number generator. This module
4141+ provides a managed way either to get random numbers from a
4242+ NIST-approved random number generator or /dev/random. The NIST
4343+ random number generator gets its entropy from /dev/random, but
4444+ operates 9x-10x faster than it.
4545+4646+ @discussion It is inconvenient to call system random number generators
4747+ directly. In the simple case of calling /dev/random, the caller
4848+ has to open the device and close it in addition to managing it
4949+ while it's open. This module has as its immediate raison d'�tre
5050+ the inconvenience of doing this. It manages a file descriptor to
5151+ /dev/random including the exception processing of what happens
5252+ in a fork() and exec(). Call CCRandomCopyBytes() and all the
5353+ fiddly bits are managed for you. Just get on with whatever you
5454+ were really trying to do.
5555+5656+ More importantly, though, it also manages a FIPS 140-compliant
5757+ way to get random numbers. NIST created in their document SP
5858+ 800-90 a new type of AES-based "Deterministic Random Bit
5959+ Generator" (DRBG) (what is often called a PRNG) and guidelines
6060+ on how to use it. There are two reasons to prefer it over
6161+ directly calling /dev/random. It's a standard and immediately
6262+ compliant with FIPS 140, and it is dramatically faster per-byte.
6363+ For complete disclosure, this implements an AES-CTR DRBG with
6464+ derivation function using AES-128 as the cipher and prediction
6565+ resistance.
6666+6767+ Thus, we provide two RNGs to call, kCCRandomDefault (the NIST
6868+ one) and kCCRandomDevRandom (a managed wrapper around
6969+ /dev/random). If you are doing anything involving security, call
7070+ the default one. You'll be glad you did, because it does much
7171+ security-related housekeeping for you and you don't have to
7272+ think about it. Really.
7373+7474+ In implementation details, the first time you call
7575+ CCRandomCopyBytes(), it will open up /dev/random and seed the RNG
7676+ with 64 bytes. After each call, there is a reseed operation that
7777+ happens on an async GCD queue that reseeds with 32 bytes and a
7878+ nonce from mach_absolute_time(). All access to the internal DRBG
7979+ is serialized through a GCD queue and is therefore thread safe.
8080+8181+ Should you need to create your own RNG context or have a secondary
8282+ RNG context, CCRNGCreate() and CCRNGRelease() will let you create
8383+ an RNG yourself and then call CCRandomCopyBytes() with that
8484+ context.
8585+ */
8686+8787+#include <CommonCrypto/CommonRandom.h>
8888+8989+#if defined(__cplusplus)
9090+extern "C" {
9191+#endif
9292+9393+/*!
9494+ @typedef CCRandomRef
9595+ @abstract Abstract Reference to a random number generator.
9696+9797+*/
9898+#ifndef COMMONRANDOMPRIV_H // Check for the private header
9999+typedef struct __CCRandom *CCRandomRef;
100100+#endif
101101+102102+/*!
103103+ @function CCRandomCopyBytes
104104+105105+ @abstract Return random bytes in a buffer allocated by the caller.
106106+107107+ @discussion The default PRNG returns cryptographically strong random
108108+ bits suitable for use as cryptographic keys, IVs, nonces etc.
109109+110110+ @param rnd The random number generator to use. Pre-defined values:
111111+ kCCRandomDefault, the NIST AES-based one and
112112+ kCCRandomDevRandom, /dev/random itself.
113113+114114+ Alternately, you can create one with CCRNGCreate().
115115+116116+ @param bytes Pointer to the return buffer.
117117+ @param count Number of random bytes to return.
118118+119119+ @result Return kCCSuccess on success. Other values are ...
120120+ */
121121+122122+int CCRandomCopyBytes(CCRandomRef rnd, void *bytes, size_t count)
123123+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0);
124124+125125+extern const CCRandomRef kCCRandomDefault
126126+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0);
127127+128128+extern const CCRandomRef kCCRandomDevRandom
129129+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0);
130130+131131+/*!
132132+ @function CCRNGCreate
133133+134134+ @abstract Create an RNG context.
135135+136136+ @discussion This creates a CCRandomRef that you can then pass into
137137+ CCRandomCopyBytes(). Only call this if you need to create
138138+ your own context. You can call CCRandomCopyBytes() with this
139139+ context. Remember to release it.
140140+141141+ @param options Option flags. See below. Unless you have a very
142142+ good reason, just use kCCRNGOptionCryptoRNG.
143143+144144+ @param rngRef A pointer to a CCRandomRef.
145145+146146+ @result Returns kCCSuccess on success.
147147+148148+149149+ */
150150+151151+CCRNGStatus
152152+CCRNGCreate(uint32_t options, CCRandomRef *rngRef)
153153+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0);
154154+155155+/*!
156156+ @function CCRNGRelease
157157+158158+ @abstract Release an RNG context.
159159+160160+ @discussion This releases and deallocates a context.
161161+162162+ @param rng A CCRandomRef.
163163+164164+ @result Returns kCCSuccess on success.
165165+166166+167167+ */
168168+169169+CCRNGStatus
170170+CCRNGRelease(CCRandomRef rng)
171171+__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_5_0);
172172+173173+174174+/*
175175+ Options flags
176176+177177+ The option flags are not exposed through the default use of CCRandomGetBytes().
178178+ They are only exposed through direct use of a CCRandomRef.
179179+180180+ The polarity is reversed here for two reasons. One is that I want people to
181181+ think before they make a non-FIPS, predictable RNG. If you're doing any sort of
182182+ crypto, you want FIPS and you want prediction resistance. Prediction resistance
183183+ reseeds after every query which is slightly slower, but more secure. Non-FIPS
184184+ is about 20% faster for very large reads, where very large means well over a MB
185185+ per get, which you will probably never do. If you pull under 500 bytes from the
186186+ RNG, there is *NO* change in performance for non-FIPS.
187187+188188+ Non-FIPS makes two changes. First, it increments the counter in machine-natural
189189+ order, which on little-endian machines makes a very small performance
190190+ improvement. It saves you two byte-swaps for every 32-bit increment of the
191191+ counter, for every int that has to be incremented, which is admittedly not
192192+ much. It is so much not much that this is a compile-time option in the DRBG,
193193+ and likely to be turned off.
194194+195195+ But something that makes a difference is that it reads from the DRBG in one
196196+ lump sum, instead of in 500 byte chunks, as FIPS demands. On a 50MB test, runs
197197+ about 20% faster, but obviously for 500 bytes would run the same.
198198+199199+ Arguably, we should remove the non-FIPS thing because in most circumstances it
200200+ matters naught. Also, as we've said before, if you're interested in security,
201201+ you shouldn't be worrying about a small performance tweaks.
202202+203203+ Prediction resistance re-seeds the DRBG after every request with 32 bytes from
204204+ /dev/random and a timestamp from mach_absolute_time(). This is a legitimate
205205+ thing you might want and a difference between a "random" and a "urandom"
206206+ variant.
207207+208208+*/
209209+210210+enum {
211211+ kCCRNGOptionIgnoreFIPS = 0x00000001,
212212+ kCCRNGOptionNoPredictionResistance = 0x00000002,
213213+214214+ kCCRNGOptionCryptoRNG = 0x00000000,
215215+};
216216+217217+// Accessor functions to get the rng "states" for internal Security Framework
218218+// use.
219219+#include <corecrypto/ccdrbg.h>
220220+#include <corecrypto/ccrng_system.h>
221221+222222+struct ccrng_state *ccDevRandomGetRngState(void)
223223+__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0);
224224+225225+struct ccrng_state *ccDRBGGetRngState(void)
226226+__OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_6_0);
227227+228228+229229+#if defined(__cplusplus)
230230+}
231231+#endif
232232+233233+#endif /* COMMONRANDOM_H */
234234+