Apache Portable Runtime
apr_random.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_RANDOM_H
00018 #define APR_RANDOM_H
00019 
00020 /**
00021  * @file apr_random.h
00022  * @brief APR PRNG routines
00023  */
00024 
00025 #include "apr_pools.h"
00026 #include "apr_thread_proc.h"
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif /* __cplusplus */
00031 
00032 /**
00033  * @defgroup apr_random PRNG Routines
00034  * @ingroup APR
00035  * @{
00036  */
00037 
00038 typedef struct apr_crypto_hash_t apr_crypto_hash_t;
00039 
00040 typedef void apr_crypto_hash_init_t(apr_crypto_hash_t *hash);
00041 typedef void apr_crypto_hash_add_t(apr_crypto_hash_t *hash, const void *data,
00042                                    apr_size_t bytes);
00043 typedef void apr_crypto_hash_finish_t(apr_crypto_hash_t *hash,
00044                                       unsigned char *result);
00045 
00046 
00047 /* FIXME: make this opaque */
00048 struct apr_crypto_hash_t {
00049     apr_crypto_hash_init_t *init;
00050     apr_crypto_hash_add_t *add;
00051     apr_crypto_hash_finish_t *finish;
00052     apr_size_t size;
00053     void *data;
00054 };
00055 
00056 /**
00057  * Allocate and initialize the SHA-256 context
00058  * @param p The pool to allocate from
00059  */
00060 APR_DECLARE(apr_crypto_hash_t *) apr_crypto_sha256_new(apr_pool_t *p);
00061 
00062 /** Opaque PRNG structure. */
00063 typedef struct apr_random_t apr_random_t;
00064 
00065 /**
00066  * Initialize a PRNG state
00067  * @param g The PRNG state
00068  * @param p The pool to allocate from
00069  * @param pool_hash Pool hash functions
00070  * @param key_hash Key hash functions
00071  * @param prng_hash PRNG hash functions
00072  */
00073 APR_DECLARE(void) apr_random_init(apr_random_t *g, apr_pool_t *p,
00074                                   apr_crypto_hash_t *pool_hash,
00075                                   apr_crypto_hash_t *key_hash,
00076                                   apr_crypto_hash_t *prng_hash);
00077 /**
00078  * Allocate and initialize (apr_crypto_sha256_new) a new PRNG state.
00079  * @param p The pool to allocate from
00080  */
00081 APR_DECLARE(apr_random_t *) apr_random_standard_new(apr_pool_t *p);
00082 
00083 /**
00084  * Mix the randomness pools.
00085  * @param g The PRNG state
00086  * @param entropy_ Entropy buffer
00087  * @param bytes Length of entropy_ in bytes
00088  */
00089 APR_DECLARE(void) apr_random_add_entropy(apr_random_t *g,
00090                                          const void *entropy_,
00091                                          apr_size_t bytes);
00092 /**
00093  * Generate cryptographically insecure random bytes.
00094  * @param g The RNG state
00095  * @param random Buffer to fill with random bytes
00096  * @param bytes Length of buffer in bytes
00097  */
00098 APR_DECLARE(apr_status_t) apr_random_insecure_bytes(apr_random_t *g,
00099                                                     void *random,
00100                                                     apr_size_t bytes);
00101 
00102 /**
00103  * Generate cryptographically secure random bytes.
00104  * @param g The RNG state
00105  * @param random Buffer to fill with random bytes
00106  * @param bytes Length of buffer in bytes
00107  */
00108 APR_DECLARE(apr_status_t) apr_random_secure_bytes(apr_random_t *g,
00109                                                   void *random,
00110                                                   apr_size_t bytes);
00111 /**
00112  * Ensures that E bits of conditional entropy are mixed into the PRNG
00113  * before any further randomness is extracted.
00114  * @param g The RNG state
00115  */
00116 APR_DECLARE(void) apr_random_barrier(apr_random_t *g);
00117 
00118 /**
00119  * Return APR_SUCCESS if the cryptographic PRNG has been seeded with
00120  * enough data, APR_ENOTENOUGHENTROPY otherwise.
00121  * @param r The RNG state
00122  */
00123 APR_DECLARE(apr_status_t) apr_random_secure_ready(apr_random_t *r);
00124 
00125 /**
00126  * Return APR_SUCCESS if the PRNG has been seeded with enough data,
00127  * APR_ENOTENOUGHENTROPY otherwise.
00128  * @param r The PRNG state
00129  */
00130 APR_DECLARE(apr_status_t) apr_random_insecure_ready(apr_random_t *r);
00131 
00132 /**
00133  * Mix the randomness pools after forking.
00134  * @param proc The resulting process handle from apr_proc_fork()
00135  * @remark Call this in the child after forking to mix the randomness
00136  * pools. Note that its generally a bad idea to fork a process with a
00137  * real PRNG in it - better to have the PRNG externally and get the
00138  * randomness from there. However, if you really must do it, then you
00139  * should supply all your entropy to all the PRNGs - don't worry, they
00140  * won't produce the same output.
00141  * @remark Note that apr_proc_fork() calls this for you, so only weird
00142  * applications need ever call it themselves.
00143  * @internal
00144  */
00145 APR_DECLARE(void) apr_random_after_fork(apr_proc_t *proc);
00146 
00147 /** @} */
00148 
00149 #ifdef __cplusplus
00150 }
00151 #endif
00152 
00153 #endif /* !APR_RANDOM_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines