github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_2_34/include/apr_random.h (about)

     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 */