1/*
2 * cckprng.h
3 * corecrypto
4 *
5 * Created on 12/7/2017
6 *
7 * Copyright (c) 2017 Apple Inc. All rights reserved.
8 *
9 */
10
11#ifndef _CORECRYPTO_CCKPRNG_H_
12#define _CORECRYPTO_CCKPRNG_H_
13
14#include <corecrypto/cc.h>
15
16typedef struct PRNG *PrngRef;
17typedef struct cckprng_ctx *cckprng_ctx_t;
18
19struct cckprng_ctx {
20 PrngRef prng;
21 uint64_t bytes_since_entropy;
22 uint64_t bytes_generated;
23};
24
25#define CCKPRNG_ENTROPY_INTERVAL (1 << 14)
26#define CCKPRNG_RESEED_NTICKS 50
27
28/*
29 @function cckprng_init
30 @abstract Initialize a kernel PRNG context.
31
32 @param ctx Context for this instance
33 @param nbytes Length of the seed in bytes
34 @param seed Pointer to a high-entropy seed
35
36 @result @p CCKPRNG_OK iff successful. Panic on @p CCKPRNG_ABORT.
37*/
38int cckprng_init(cckprng_ctx_t ctx, size_t nbytes, const void *seed);
39
40/*
41 @function cckprng_reseed
42 @abstract Reseed a kernel PRNG context immediately.
43
44 @param ctx Context for this instance
45 @param nbytes Length of the seed in bytes
46 @param seed Pointer to a high-entropy seed
47
48 @result @p CCKPRNG_OK iff successful. Panic on @p CCKPRNG_ABORT.
49*/
50int cckprng_reseed(cckprng_ctx_t ctx, size_t nbytes, const void *seed);
51
52/*
53 @function cckprng_addentropy
54 @abstract Add entropy to a kernel PRNG context.
55
56 @param ctx Context for this instance
57 @param nbytes Length of the input entropy in bytes
58 @param seed Pointer to input entropy
59
60 @result @p CCKPRNG_OK iff successful. Panic on @p CCKPRNG_ABORT.
61
62 @discussion Input entropy is stored internally and consumed at the
63 opportune moment. This will not necessarily be before the next call
64 to @p cckprng_generate. To force an immediate reseed, call @p
65 cckprng_reseed.
66*/
67int cckprng_addentropy(cckprng_ctx_t ctx, size_t nbytes, const void *entropy);
68
69/*
70 @function cckprng_generate
71 @abstract Generate random values for use in applications.
72
73 @param ctx Context for this instance
74 @param nbytes Length of the desired output in bytes
75 @param seed Pointer to the output buffer
76
77 @result @p CCKPRNG_OK iff successful. Panic on @p
78 CCKPRNG_ABORT. Provide input to @p cckprng_addentropy on @p
79 CCKPRNG_NEED_ENTROPY.
80*/
81int cckprng_generate(cckprng_ctx_t ctx, size_t nbytes, void *out);
82
83#endif /* _CORECRYPTO_CCKPRNG_H_ */
84