EXTERNAL_HEADERS/corecrypto/cckprng.h

   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_ */