1 /* Copyright (c) (2010-2020,2022) Apple Inc. All rights reserved. 2 * 3 * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which 4 * is contained in the License.txt file distributed with corecrypto) and only to 5 * people who accept that license. IMPORTANT: Any license rights granted to you by 6 * Apple Inc. (if any) are limited to internal use within your organization only on 7 * devices and computers you own or control, for the sole purpose of verifying the 8 * security characteristics and correct functioning of the Apple Software. You may 9 * not, directly or indirectly, redistribute the Apple Software or any portions thereof. 10 */ 11 12 #ifndef _CORECRYPTO_CCRNG_H_ 13 #define _CORECRYPTO_CCRNG_H_ 14 15 #include <corecrypto/cc.h> 16 17 #define CCRNG_STATE_COMMON \ 18 int (*CC_SPTR(ccrng_state, generate))(struct ccrng_state *rng, size_t outlen, void *out); 19 20 /*! 21 @type struct ccrng_state 22 @abstract Default state structure. Do not instantiate. ccrng() returns a reference to this structure 23 */ 24 struct ccrng_state { 25 CCRNG_STATE_COMMON 26 }; 27 28 /*! 29 @function ccrng 30 @abstract Get a handle to a secure RNG 31 32 @param error A pointer to set in case of error; may be null 33 34 @result A handle to a secure RNG, or null if one cannot be initialized successfully 35 36 @discussion 37 This function returns a pointer to the most appropriate RNG for the 38 environment. This may be a TRNG if one is available. Otherwise, it is 39 a PRNG offering several features: 40 - Good performance 41 - FIPS Compliant: NIST SP800-90A + FIPS 140-2 42 - Seeded from the appropriate entropy source for the platform 43 - Provides at least 128-bit security 44 - Backtracing resistance 45 - Prediction break (after reseed) 46 */ 47 struct ccrng_state *ccrng(int *error); 48 49 /*! 50 @function ccrng_generate 51 @abstract Generate `outlen` bytes of output, stored in `out`, using ccrng_state `rng`. 52 53 @param rng `struct ccrng_state` representing the state of the RNG. 54 @param outlen Amount of random bytes to generate. 55 @param out Pointer to memory where random bytes are stored, of size at least `outlen`. 56 57 @result 0 on success and nonzero on failure. 58 */ 59 #define ccrng_generate(rng, outlen, out) \ 60 ((rng)->generate((struct ccrng_state *)(rng), (outlen), (out))) 61 62 #if !CC_EXCLAVEKIT 63 /*! 64 @function ccrng_uniform 65 @abstract Generate a random value in @p [0, bound). 66 67 @param rng The state of the RNG. 68 @param bound The exclusive upper bound on the output. 69 @param rand A pointer to a single @p uint64_t to store the result. 70 71 @result Returns zero iff the operation is successful. 72 */ 73 int ccrng_uniform(struct ccrng_state *rng, uint64_t bound, uint64_t *rand); 74 #endif 75 76 #endif /* _CORECRYPTO_CCRNG_H_ */ 77