Apache Portable Runtime
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apr_random.h
Go to the documentation of this file.
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
29 extern "C" {
30 #endif /* __cplusplus */
31 
32 /**
33  * @defgroup apr_random PRNG Routines
34  * @ingroup APR
35  * @{
36  */
37 
39 
40 typedef void apr_crypto_hash_init_t(apr_crypto_hash_t *hash);
41 typedef void apr_crypto_hash_add_t(apr_crypto_hash_t *hash, const void *data,
42  apr_size_t bytes);
43 typedef void apr_crypto_hash_finish_t(apr_crypto_hash_t *hash,
44  unsigned char *result);
45 
46 
47 /* FIXME: make this opaque */
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  */
61 
62 /** Opaque PRNG structure. */
63 typedef 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  */
73 APR_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  */
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  */
89 APR_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  */
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  */
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  */
116 APR_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  */
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  */
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  */
146 
147 /** @} */
148 
149 #ifdef __cplusplus
150 }
151 #endif
152 
153 #endif /* !APR_RANDOM_H */