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 | |
16 | typedef struct PRNG *PrngRef; |
17 | typedef struct cckprng_ctx *cckprng_ctx_t; |
18 | |
19 | struct 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 | */ |
38 | int 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 | */ |
50 | int 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 | */ |
67 | int 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 | */ |
81 | int cckprng_generate(cckprng_ctx_t ctx, size_t nbytes, void *out); |
82 | |
83 | #endif /* _CORECRYPTO_CCKPRNG_H_ */ |
84 | |