contrib/apr/include/apr_random.h

   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
  38 typedef struct apr_crypto_hash_t apr_crypto_hash_t;
  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 */
  48 struct 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  */
  60 APR_DECLARE(apr_crypto_hash_t *) apr_crypto_sha256_new(apr_pool_t *p);
  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  */
  81 APR_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  */
  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  */
  98 APR_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  */
 108 APR_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  */
 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  */
 123 APR_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  */
 130 APR_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  */
 145 APR_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 */