xnu-4570.71.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..698f412ca76a763b3fb5b4e3a8e49c88553de3d0 100644 (file)
--- a/EXTERNAL_HEADERS/corecrypto/ccrng.h
+++ b/EXTERNAL_HEADERS/corecrypto/ccrng.h
@@ -2,31 +2,59 @@
  *  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>
+#include <corecrypto/cc.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
+#define CCERR_DEVICE                   -100
+#define CCERR_INTERUPTS                -101
+#define CCERR_CRYPTO_CONFIG            -102
+#define CCERR_PERMS                    -103
+#define CCERR_PARAMETER                -104
+#define CCERR_MEMORY                   -105
+#define CCERR_FILEDESC                 -106
+#define CCERR_OUT_OF_ENTROPY           -107
+#define CCERR_INTERNAL                 -108
+#define CCERR_ATFORK                   -109
+#define CCERR_OVERFLOW                 -110
 
 #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((rng), (outlen), (out)))
 
 #endif /* _CORECRYPTO_CCRNG_H_ */