[apple/xnu.git] / osfmk / prng / entropy.h

/*
 * Copyright (c) 2019 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef _PRNG_ENTROPY_H_
#define _PRNG_ENTROPY_H_

__BEGIN_DECLS

#ifdef XNU_KERNEL_PRIVATE

// The below three definitions are utilized when the kernel is in
// "normal" operation, that is when we are *not* interested in collecting
// entropy.

// Indicates the number of bytes in the entropy buffer
#define ENTROPY_BUFFER_BYTE_SIZE 32

// Indicates the number of uint32_t's in the entropy buffer
#define ENTROPY_BUFFER_SIZE (ENTROPY_BUFFER_BYTE_SIZE / sizeof(uint32_t))

// Mask applied to EntropyData.sample_count to get an
// index suitable for storing the next sample in
// EntropyData.buffer. Note that ENTROPY_BUFFER_SIZE must be a power
// of two for the following mask calculation to be valid.
#define ENTROPY_BUFFER_INDEX_MASK (ENTROPY_BUFFER_SIZE - 1)

typedef struct entropy_data {
	/*
	 * TODO: Should sample_count be volatile?  Are we exposed to any races that
	 * we care about if it is not?
	 */

	// At 32 bits, this counter can overflow. Since we're primarily
	// interested in the delta from one read to the next, we don't
	// worry about this too much.
	uint32_t sample_count;

	// We point to either a static array when operating normally or
	// a dynamically allocated array when we wish to collect entropy
	// data. This decision is based on the presence of the boot
	// argument "ebsz".
	uint32_t *buffer;

	// The entropy buffer size in bytes. This must be a power of 2.
	uint32_t buffer_size;

	// The mask used to index into the entropy buffer for storing
	// the next entropy sample.
	uint32_t buffer_index_mask;

	// The mask used to include the previous entropy buffer contents
	// when updating the entropy buffer. When in entropy collection
	// mode this is set to zero so that we can gather the raw entropy.
	// In normal operation this is set to (uint32_t) -1.
	uint32_t ror_mask;
} entropy_data_t;

extern entropy_data_t EntropyData;

/* Trace codes for DBG_SEC_KERNEL: */
#define ENTROPY_READ(n) SECURITYDBG_CODE(DBG_SEC_KERNEL, n) /* n: 0 .. 3 */

#endif /* XNU_KERNEL_PRIVATE */

void entropy_buffer_init(void);

__END_DECLS

#endif /* _PRNG_ENTROPY_H_ */
Commit	Line	Data
f427ee49 A	1	/*
	2	* Copyright (c) 2019 Apple 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 _PRNG_ENTROPY_H_
	30	#define _PRNG_ENTROPY_H_
	31
	32	__BEGIN_DECLS
	33
	34	#ifdef XNU_KERNEL_PRIVATE
	35
	36	// The below three definitions are utilized when the kernel is in
	37	// "normal" operation, that is when we are not interested in collecting
	38	// entropy.
	39
	40	// Indicates the number of bytes in the entropy buffer
	41	#define ENTROPY_BUFFER_BYTE_SIZE 32
	42
	43	// Indicates the number of uint32_t's in the entropy buffer
	44	#define ENTROPY_BUFFER_SIZE (ENTROPY_BUFFER_BYTE_SIZE / sizeof(uint32_t))
	45
	46	// Mask applied to EntropyData.sample_count to get an
	47	// index suitable for storing the next sample in
	48	// EntropyData.buffer. Note that ENTROPY_BUFFER_SIZE must be a power
	49	// of two for the following mask calculation to be valid.
	50	#define ENTROPY_BUFFER_INDEX_MASK (ENTROPY_BUFFER_SIZE - 1)
	51
	52	typedef struct entropy_data {
	53	/*
	54	* TODO: Should sample_count be volatile? Are we exposed to any races that
	55	* we care about if it is not?
	56	*/
	57
	58	// At 32 bits, this counter can overflow. Since we're primarily
	59	// interested in the delta from one read to the next, we don't
	60	// worry about this too much.
	61	uint32_t sample_count;
	62
	63	// We point to either a static array when operating normally or
	64	// a dynamically allocated array when we wish to collect entropy
65	// data. This decision is based on the presence of the boot
66	// argument "ebsz".
67	uint32_t *buffer;
68
69	// The entropy buffer size in bytes. This must be a power of 2.
70	uint32_t buffer_size;
71
72	// The mask used to index into the entropy buffer for storing
73	// the next entropy sample.
74	uint32_t buffer_index_mask;
75
76	// The mask used to include the previous entropy buffer contents
77	// when updating the entropy buffer. When in entropy collection
78	// mode this is set to zero so that we can gather the raw entropy.
79	// In normal operation this is set to (uint32_t) -1.
80	uint32_t ror_mask;
81	} entropy_data_t;
82
83	extern entropy_data_t EntropyData;
84
85	/* Trace codes for DBG_SEC_KERNEL: */
86	#define ENTROPY_READ(n) SECURITYDBG_CODE(DBG_SEC_KERNEL, n) /* n: 0 .. 3 */
87
88	#endif /* XNU_KERNEL_PRIVATE */
89
90	void entropy_buffer_init(void);
91
92	__END_DECLS
93
94	#endif /* _PRNG_ENTROPY_H_ */