xnu-4903.221.2.tar.gz

[apple/xnu.git] / EXTERNAL_HEADERS / corecrypto / ccrng.h

diff --git a/EXTERNAL_HEADERS/corecrypto/ccrng.h b/EXTERNAL_HEADERS/corecrypto/ccrng.h
index c748bc6e6a1739a9034f6aa08b4b5cf00168730e..c6bc18a90b339c3a511cdfdb5f6b05ff168f43ca 100644 (file)
--- a/EXTERNAL_HEADERS/corecrypto/ccrng.h
+++ b/EXTERNAL_HEADERS/corecrypto/ccrng.h
@@ -2,31 +2,47 @@
  *  ccrng.h
  *  corecrypto
  *
- *  Created by Fabrice Gautier on 12/13/10.
- *  Copyright 2010 Apple, Inc. All rights reserved.
+ *  Created on 12/13/2010
+ *
+ *  Copyright (c) 2010,2011,2013,2014,2015 Apple Inc. All rights reserved.
  *
  */
 
 #ifndef _CORECRYPTO_CCRNG_H_
 #define _CORECRYPTO_CCRNG_H_
 
-#include <stdint.h>
-
-#define CC_ERR_DEVICE -100
-#define CC_ERR_INTERUPTS -101
-#define CC_ERR_CRYPTO_CONFIG -102
-#define CC_ERR_PERMS -103
-#define CC_ERR_PARAMETER -104
-#define CC_ERR_MEMORY -105
+#include <corecrypto/cc.h>
 
 #define CCRNG_STATE_COMMON                                                          \
-    int (*generate)(struct ccrng_state *rng, unsigned long outlen, void *out);
+    int (*generate)(struct ccrng_state *rng, size_t outlen, void *out);
 
-/* default state structure - do not instantiate, instead use the specific one you need */
+/* default state structure. Do not instantiate, ccrng() returns a reference to this structure */
 struct ccrng_state {
     CCRNG_STATE_COMMON
 };
 
-#define ccrng_generate(ctx, outlen, out) ((ctx)->generate((ctx), (outlen), (out)))
+/*!
+ @function   ccrng
+ @abstract   initializes a AES-CTR mode cryptographic random number generator and returns the statically alocated rng object. 
+             Getting a pointer to a ccrng has never been simpler! 
+             Call this function, get an rng object and then pass the object to ccrng_generate() to generate randoms.
+             ccrng() may be called more than once. It returns pointer to the same object on all calls.
+
+ @result  a cryptographically secure random number generator or NULL if fails
+ 
+ @discussion 
+ - It is significantly faster than using the system /dev/random
+ - FIPS Compliant: NIST SP800-80A + FIPS 140-2
+ - Seeded from the system entropy.
+ - Provides at least 128bit security if the system provide 2bit of entropy / byte.
+ - Entropy accumulation
+ - Backtracing resistance
+ - Prediction break with frequent (asynchronous) reseed
+ */
+
+struct ccrng_state *ccrng(int *error);
+
+//call this macro with the rng argument set to output of the call to the ccrng() function
+#define ccrng_generate(rng, outlen, out) ((rng)->generate((struct ccrng_state *)(rng), (outlen), (out)))
 
 #endif /* _CORECRYPTO_CCRNG_H_ */