1 /* 2 * Copyright (c) 2016 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_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. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29 #ifndef _RAND_H 30 #define _RAND_H 31 32 #include <libkern/crypto/crypto.h> 33 34 __BEGIN_DECLS 35 36 // A handle to a random generator suitable for use with 37 // crypto_random_generate. 38 typedef void *crypto_random_ctx_t; 39 40 // The maximum size (in bytes) of a random generator. 41 #define CRYPTO_RANDOM_MAX_CTX_SIZE ((size_t)256) 42 43 typedef void (*crypto_random_generate_fn_t)( 44 crypto_random_ctx_t ctx, 45 void *random, 46 size_t random_size); 47 48 typedef void (*crypto_random_uniform_fn_t)( 49 crypto_random_ctx_t ctx, 50 uint64_t bound, 51 uint64_t *random); 52 53 typedef size_t (*crypto_random_kmem_ctx_size_fn_t)(void); 54 55 typedef void (*crypto_random_kmem_init_fn_t)( 56 crypto_random_ctx_t ctx); 57 58 #if XNU_KERNEL_PRIVATE 59 60 int cc_rand_generate(void *out, size_t outlen); 61 62 // Generate random data with the supplied handle to a random 63 // generator. The behavior of this function (e.g. the quality of the 64 // randomness, whether it might acquire a lock, the cryptographic 65 // primitives used) depends on the semantics of the generator. 66 void crypto_random_generate( 67 crypto_random_ctx_t ctx, 68 void *random, 69 size_t random_size); 70 71 // Generate a random value in the range [0, bound), i.e. including 72 // zero and excluding the bound. The generated value is stored in the 73 // random pointer which should point to a single value. As above, the 74 // behavior of this function depends in part on the semantics of the 75 // generator. 76 void crypto_random_uniform( 77 crypto_random_ctx_t ctx, 78 uint64_t bound, 79 uint64_t *random); 80 81 // The following two functions are for use in the kmem subsystem 82 // only. They are NOT guaranteed to provide cryptographic randomness 83 // and should not be used elsewhere. 84 85 // Return the size needed for a random generator to be used by 86 // kmem. (See the discussion below for the semantics of this 87 // generator.) 88 // 89 // The returned value may vary by platform, but it is guaranteed to be 90 // no larger than CRYPTO_RANDOM_MAX_CTX_SIZE. 91 size_t crypto_random_kmem_ctx_size(void); 92 93 // Initialize the handle with a random generator for use by kmem. This 94 // function should only be called by kmem. 95 // 96 // The handle should point to memory at least as large as 97 // crypto_random_kmem_ctx_size() indicates. 98 // 99 // This generator is NOT guaranteed to provide cryptographic 100 // randomness. 101 // 102 // The initialized generator is guaranteed not to acquire a 103 // lock. (Note, however, that this initialization function MAY acquire 104 // a lock.) 105 // 106 // The initialized generator is guaranteed not to touch FP registers 107 // on Intel. 108 void crypto_random_kmem_init( 109 crypto_random_ctx_t ctx); 110 111 #endif /* XNU_KERNEL_PRIVATE */ 112 113 int random_buf(void *buf, size_t buflen); 114 115 __END_DECLS 116 117 #endif 118