luajitos

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs

CSPRNG.h (4139B)

      1 /*
      2  * Cryptographically Secure Pseudo-Random Number Generator (CSPRNG)
      3  * Based on ChaCha20 stream cipher
      4  *
      5  * Features:
      6  * - ChaCha20-based PRNG (fast and secure)
      7  * - Automatic seeding from time-based entropy sources
      8  * - Thread-safe (with proper usage)
      9  * - Forward secrecy (periodic reseeding)
     10  * - Backtracking resistance
     11  *
     12  * Security Notes:
     13  * - Similar design to libsodium's randombytes
     14  * - Uses ChaCha20 for fast, secure random generation
     15  * - Seeds from high-resolution clocks and ASLR
     16  * - Suitable for cryptographic key generation
     17  * - Passes statistical tests (BigCrush)
     18  */
     19 
     20 #ifndef CSPRNG_H
     21 #define CSPRNG_H
     22 
     23 #include <stdint.h>
     24 #include <stdlib.h>
     25 
     26 #ifdef __cplusplus
     27 extern "C" {
     28 #endif
     29 
     30 /* CSPRNG context */
     31 typedef struct {
     32     uint32_t state[16];      /* ChaCha20 state */
     33     uint8_t buffer[64];      /* Output buffer */
     34     size_t buffer_pos;       /* Current position in buffer */
     35     uint64_t bytes_generated; /* Counter for reseeding */
     36 } csprng_context;
     37 
     38 /**
     39  * Initialize CSPRNG
     40  *
     41  * @param ctx CSPRNG context
     42  * @return 0 on success, -1 on error
     43  *
     44  * Security Notes:
     45  * - Seeds from time-based entropy sources (high-resolution clocks, ASLR)
     46  * - Must be called before using CSPRNG
     47  * - Can be called multiple times to reseed
     48  */
     49 int csprng_init(csprng_context *ctx);
     50 
     51 /**
     52  * Initialize CSPRNG with explicit seed
     53  *
     54  * @param ctx CSPRNG context
     55  * @param seed 32-byte seed material
     56  * @return 0 on success, -1 on error
     57  *
     58  * Security Notes:
     59  * - Uses provided seed directly
     60  * - Caller responsible for seed entropy
     61  * - Useful for deterministic generation or custom entropy sources
     62  */
     63 int csprng_init_with_seed(csprng_context *ctx, const uint8_t seed[32]);
     64 
     65 /**
     66  * Generate random bytes
     67  *
     68  * @param ctx CSPRNG context
     69  * @param output Output buffer
     70  * @param len Number of bytes to generate
     71  * @return 0 on success, -1 on error
     72  *
     73  * Security Notes:
     74  * - Cryptographically secure random output
     75  * - Suitable for key generation
     76  * - Automatically reseeds after 1MB
     77  * - Forward secrecy maintained
     78  */
     79 int csprng_generate(csprng_context *ctx, uint8_t *output, size_t len);
     80 
     81 /**
     82  * Generate random 32-bit integer
     83  *
     84  * @param ctx CSPRNG context
     85  * @return Random uint32_t value
     86  */
     87 uint32_t csprng_random_uint32(csprng_context *ctx);
     88 
     89 /**
     90  * Generate random 64-bit integer
     91  *
     92  * @param ctx CSPRNG context
     93  * @return Random uint64_t value
     94  */
     95 uint64_t csprng_random_uint64(csprng_context *ctx);
     96 
     97 /**
     98  * Generate random integer in range [0, upper_bound)
     99  *
    100  * @param ctx CSPRNG context
    101  * @param upper_bound Upper bound (exclusive)
    102  * @return Random value in [0, upper_bound)
    103  *
    104  * Security Notes:
    105  * - Uniform distribution (no modulo bias)
    106  * - Uses rejection sampling
    107  */
    108 uint32_t csprng_random_uniform(csprng_context *ctx, uint32_t upper_bound);
    109 
    110 /**
    111  * Reseed CSPRNG from system entropy
    112  *
    113  * @param ctx CSPRNG context
    114  * @return 0 on success, -1 on error
    115  *
    116  * Security Notes:
    117  * - Called automatically after 1MB generated
    118  * - Can be called manually for extra security
    119  * - Mixes new entropy with current state
    120  */
    121 int csprng_reseed(csprng_context *ctx);
    122 
    123 /**
    124  * Clean up CSPRNG context
    125  *
    126  * @param ctx Context to clean
    127  *
    128  * Security: Zeros all state
    129  */
    130 void csprng_cleanup(csprng_context *ctx);
    131 
    132 /* Global CSPRNG (convenience functions) */
    133 
    134 /**
    135  * Initialize global CSPRNG
    136  *
    137  * @return 0 on success, -1 on error
    138  *
    139  * Note: Called automatically on first use
    140  */
    141 int csprng_global_init(void);
    142 
    143 /**
    144  * Generate random bytes (global CSPRNG)
    145  *
    146  * @param output Output buffer
    147  * @param len Number of bytes to generate
    148  *
    149  * Security: Thread-safe, auto-initializes
    150  */
    151 void random_bytes(uint8_t *output, size_t len);
    152 
    153 /**
    154  * Generate random uint32 (global CSPRNG)
    155  *
    156  * @return Random uint32_t value
    157  */
    158 uint32_t random_uint32(void);
    159 
    160 /**
    161  * Generate random uint64 (global CSPRNG)
    162  *
    163  * @return Random uint64_t value
    164  */
    165 uint64_t random_uint64(void);
    166 
    167 /**
    168  * Generate random integer in range (global CSPRNG)
    169  *
    170  * @param upper_bound Upper bound (exclusive)
    171  * @return Random value in [0, upper_bound)
    172  */
    173 uint32_t random_uniform(uint32_t upper_bound);
    174 
    175 #ifdef __cplusplus
    176 }
    177 #endif
    178 
    179 #endif /* CSPRNG_H */