legacy-libs/grpc/deps/grpc/third_party/boringssl/include/openssl/rand.h

   1 /* Copyright (c) 2014, Google Inc.
   2  *
   3  * Permission to use, copy, modify, and/or distribute this software for any
   4  * purpose with or without fee is hereby granted, provided that the above
   5  * copyright notice and this permission notice appear in all copies.
   6  *
   7  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   8  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   9  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  10  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  11  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  12  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  13  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
  14
  15 #ifndef OPENSSL_HEADER_RAND_H
  16 #define OPENSSL_HEADER_RAND_H
  17
  18 #include <openssl/base.h>
  19
  20 #if defined(__cplusplus)
  21 extern "C" {
  22 #endif
  23
  24
  25 // Random number generation.
  26
  27
  28 // RAND_bytes writes |len| bytes of random data to |buf| and returns one.
  29 OPENSSL_EXPORT int RAND_bytes(uint8_t *buf, size_t len);
  30
  31 // RAND_cleanup frees any resources used by the RNG. This is not safe if other
  32 // threads might still be calling |RAND_bytes|.
  33 OPENSSL_EXPORT void RAND_cleanup(void);
  34
  35
  36 // Obscure functions.
  37
  38 #if !defined(OPENSSL_WINDOWS)
  39 // RAND_set_urandom_fd causes the module to use a copy of |fd| for system
  40 // randomness rather opening /dev/urandom internally. The caller retains
  41 // ownership of |fd| and is at liberty to close it at any time. This is useful
  42 // if, due to a sandbox, /dev/urandom isn't available. If used, it must be
  43 // called before the first call to |RAND_bytes|, and it is mutually exclusive
  44 // with |RAND_enable_fork_unsafe_buffering|.
  45 //
  46 // |RAND_set_urandom_fd| does not buffer any entropy, so it is safe to call
  47 // |fork| at any time after calling |RAND_set_urandom_fd|.
  48 OPENSSL_EXPORT void RAND_set_urandom_fd(int fd);
  49
  50 // RAND_enable_fork_unsafe_buffering enables efficient buffered reading of
  51 // /dev/urandom. It adds an overhead of a few KB of memory per thread. It must
  52 // be called before the first call to |RAND_bytes| and it is mutually exclusive
  53 // with calls to |RAND_set_urandom_fd|.
  54 //
  55 // If |fd| is non-negative then a copy of |fd| will be used rather than opening
  56 // /dev/urandom internally. Like |RAND_set_urandom_fd|, the caller retains
  57 // ownership of |fd|. If |fd| is negative then /dev/urandom will be opened and
  58 // any error from open(2) crashes the address space.
  59 //
  60 // It has an unusual name because the buffer is unsafe across calls to |fork|.
  61 // Hence, this function should never be called by libraries.
  62 OPENSSL_EXPORT void RAND_enable_fork_unsafe_buffering(int fd);
  63 #endif
  64
  65 #if defined(BORINGSSL_UNSAFE_DETERMINISTIC_MODE)
  66 // RAND_reset_for_fuzzing resets the fuzzer-only deterministic RNG. This
  67 // function is only defined in the fuzzer-only build configuration.
  68 OPENSSL_EXPORT void RAND_reset_for_fuzzing(void);
  69 #endif
  70
  71
  72 // Deprecated functions
  73
  74 // RAND_pseudo_bytes is a wrapper around |RAND_bytes|.
  75 OPENSSL_EXPORT int RAND_pseudo_bytes(uint8_t *buf, size_t len);
  76
  77 // RAND_seed reads a single byte of random data to ensure that any file
  78 // descriptors etc are opened.
  79 OPENSSL_EXPORT void RAND_seed(const void *buf, int num);
  80
  81 // RAND_load_file returns a nonnegative number.
  82 OPENSSL_EXPORT int RAND_load_file(const char *path, long num);
  83
  84 // RAND_file_name returns NULL.
  85 OPENSSL_EXPORT const char *RAND_file_name(char *buf, size_t num);
  86
  87 // RAND_add does nothing.
  88 OPENSSL_EXPORT void RAND_add(const void *buf, int num, double entropy);
  89
  90 // RAND_egd returns 255.
  91 OPENSSL_EXPORT int RAND_egd(const char *);
  92
  93 // RAND_poll returns one.
  94 OPENSSL_EXPORT int RAND_poll(void);
  95
  96 // RAND_status returns one.
  97 OPENSSL_EXPORT int RAND_status(void);
  98
  99 // rand_meth_st is typedefed to |RAND_METHOD| in base.h. It isn't used; it
 100 // exists only to be the return type of |RAND_SSLeay|. It's
 101 // external so that variables of this type can be initialized.
 102 struct rand_meth_st {
 103   void (*seed) (const void *buf, int num);
 104   int (*bytes) (uint8_t *buf, size_t num);
 105   void (*cleanup) (void);
 106   void (*add) (const void *buf, int num, double entropy);
 107   int (*pseudorand) (uint8_t *buf, size_t num);
 108   int (*status) (void);
 109 };
 110
 111 // RAND_SSLeay returns a pointer to a dummy |RAND_METHOD|.
 112 OPENSSL_EXPORT RAND_METHOD *RAND_SSLeay(void);
 113
 114 // RAND_get_rand_method returns |RAND_SSLeay()|.
 115 OPENSSL_EXPORT const RAND_METHOD *RAND_get_rand_method(void);
 116
 117 // RAND_set_rand_method does nothing.
 118 OPENSSL_EXPORT void RAND_set_rand_method(const RAND_METHOD *);
 119
 120
 121 #if defined(__cplusplus)
 122 }  // extern C
 123 #endif
 124
 125 #endif  // OPENSSL_HEADER_RAND_H