1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_RANDOM_H 18#define APR_RANDOM_H 19 20/** 21 * @file apr_random.h 22 * @brief APR PRNG routines 23 */ 24 25#include "apr_pools.h" 26#include "apr_thread_proc.h" 27 28#ifdef __cplusplus 29extern "C" { 30#endif /* __cplusplus */ 31 32/** 33 * @defgroup apr_random PRNG Routines 34 * @ingroup APR 35 * @{ 36 */ 37 38typedef struct apr_crypto_hash_t apr_crypto_hash_t; 39 40typedef void apr_crypto_hash_init_t(apr_crypto_hash_t *hash); 41typedef void apr_crypto_hash_add_t(apr_crypto_hash_t *hash, const void *data, 42 apr_size_t bytes); 43typedef void apr_crypto_hash_finish_t(apr_crypto_hash_t *hash, 44 unsigned char *result); 45 46 47/* FIXME: make this opaque */ 48struct apr_crypto_hash_t { 49 apr_crypto_hash_init_t *init; 50 apr_crypto_hash_add_t *add; 51 apr_crypto_hash_finish_t *finish; 52 apr_size_t size; 53 void *data; 54}; 55 56/** 57 * Allocate and initialize the SHA-256 context 58 * @param p The pool to allocate from 59 */ 60APR_DECLARE(apr_crypto_hash_t *) apr_crypto_sha256_new(apr_pool_t *p); 61 62/** Opaque PRNG structure. */ 63typedef struct apr_random_t apr_random_t; 64 65/** 66 * Initialize a PRNG state 67 * @param g The PRNG state 68 * @param p The pool to allocate from 69 * @param pool_hash Pool hash functions 70 * @param key_hash Key hash functions 71 * @param prng_hash PRNG hash functions 72 */ 73APR_DECLARE(void) apr_random_init(apr_random_t *g, apr_pool_t *p, 74 apr_crypto_hash_t *pool_hash, 75 apr_crypto_hash_t *key_hash, 76 apr_crypto_hash_t *prng_hash); 77/** 78 * Allocate and initialize (apr_crypto_sha256_new) a new PRNG state. 79 * @param p The pool to allocate from 80 */ 81APR_DECLARE(apr_random_t *) apr_random_standard_new(apr_pool_t *p); 82 83/** 84 * Mix the randomness pools. 85 * @param g The PRNG state 86 * @param entropy_ Entropy buffer 87 * @param bytes Length of entropy_ in bytes 88 */ 89APR_DECLARE(void) apr_random_add_entropy(apr_random_t *g, 90 const void *entropy_, 91 apr_size_t bytes); 92/** 93 * Generate cryptographically insecure random bytes. 94 * @param g The RNG state 95 * @param random Buffer to fill with random bytes 96 * @param bytes Length of buffer in bytes 97 */ 98APR_DECLARE(apr_status_t) apr_random_insecure_bytes(apr_random_t *g, 99 void *random, 100 apr_size_t bytes); 101 102/** 103 * Generate cryptographically secure random bytes. 104 * @param g The RNG state 105 * @param random Buffer to fill with random bytes 106 * @param bytes Length of buffer in bytes 107 */ 108APR_DECLARE(apr_status_t) apr_random_secure_bytes(apr_random_t *g, 109 void *random, 110 apr_size_t bytes); 111/** 112 * Ensures that E bits of conditional entropy are mixed into the PRNG 113 * before any further randomness is extracted. 114 * @param g The RNG state 115 */ 116APR_DECLARE(void) apr_random_barrier(apr_random_t *g); 117 118/** 119 * Return APR_SUCCESS if the cryptographic PRNG has been seeded with 120 * enough data, APR_ENOTENOUGHENTROPY otherwise. 121 * @param r The RNG state 122 */ 123APR_DECLARE(apr_status_t) apr_random_secure_ready(apr_random_t *r); 124 125/** 126 * Return APR_SUCCESS if the PRNG has been seeded with enough data, 127 * APR_ENOTENOUGHENTROPY otherwise. 128 * @param r The PRNG state 129 */ 130APR_DECLARE(apr_status_t) apr_random_insecure_ready(apr_random_t *r); 131 132/** 133 * Mix the randomness pools after forking. 134 * @param proc The resulting process handle from apr_proc_fork() 135 * @remark Call this in the child after forking to mix the randomness 136 * pools. Note that its generally a bad idea to fork a process with a 137 * real PRNG in it - better to have the PRNG externally and get the 138 * randomness from there. However, if you really must do it, then you 139 * should supply all your entropy to all the PRNGs - don't worry, they 140 * won't produce the same output. 141 * @remark Note that apr_proc_fork() calls this for you, so only weird 142 * applications need ever call it themselves. 143 * @internal 144 */ 145APR_DECLARE(void) apr_random_after_fork(apr_proc_t *proc); 146 147/** @} */ 148 149#ifdef __cplusplus 150} 151#endif 152 153#endif /* !APR_RANDOM_H */ 154