Botan  2.9.0
Crypto and TLS for C++11
os_utils.h
Go to the documentation of this file.
1 /*
2 * OS specific utility functions
3 * (C) 2015,2016,2017,2018 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7 
8 #ifndef BOTAN_OS_UTILS_H_
9 #define BOTAN_OS_UTILS_H_
10 
11 #include <botan/types.h>
12 #include <functional>
13 #include <string>
14 
15 namespace Botan {
16 
17 namespace OS {
18 
19 /*
20 * This header is internal (not installed) and these functions are not
21 * intended to be called by applications. However they are given public
22 * visibility (using BOTAN_TEST_API macro) for the tests. This also probably
23 * allows them to be overridden by the application on ELF systems, but
24 * this hasn't been tested.
25 */
26 
27 /**
28 * @return process ID assigned by the operating system.
29 * On Unix and Windows systems, this always returns a result
30 * On IncludeOS it returns 0 since there is no process ID to speak of
31 * in a unikernel.
32 */
34 
35 /**
36 * Test if we are currently running with elevated permissions
37 * eg setuid, setgid, or with POSIX caps set.
38 */
40 
41 /**
42 * @return CPU processor clock, if available
43 *
44 * On Windows, calls QueryPerformanceCounter.
45 *
46 * Under GCC or Clang on supported platforms the hardware cycle counter is queried.
47 * Currently supported processors are x86, PPC, Alpha, SPARC, IA-64, S/390x, and HP-PA.
48 * If no CPU cycle counter is available on this system, returns zero.
49 */
51 
52 /*
53 * @return best resolution timestamp available
54 *
55 * The epoch and update rate of this clock is arbitrary and depending
56 * on the hardware it may not tick at a constant rate.
57 *
58 * Uses hardware cycle counter, if available.
59 * On POSIX platforms clock_gettime is used with a monotonic timer
60 * As a final fallback std::chrono::high_resolution_clock is used.
61 */
63 
64 /**
65 * @return system clock (reflecting wall clock) with best resolution
66 * available, normalized to nanoseconds resolution.
67 */
69 
70 /**
71 * @return maximum amount of memory (in bytes) Botan could/should
72 * hyptothetically allocate for the memory poool. Reads environment
73 * variable "BOTAN_MLOCK_POOL_SIZE", set to "0" to disable pool.
74 */
76 
77 /**
78 * Return the size of a memory page, if that can be derived on the
79 * current system. Otherwise returns some default value (eg 4096)
80 */
81 size_t system_page_size();
82 
83 /**
84 * Read the value of an environment variable. Return nullptr if
85 * no such variable is set. If the process seems to be running in
86 * a privileged state (such as setuid) then always returns nullptr,
87 * similiar to glibc's secure_getenv.
88 */
89 const char* read_env_variable(const std::string& var_name);
90 
91 /**
92 * Request so many bytes of page-aligned RAM locked into memory using
93 * mlock, VirtualLock, or similar. Returns null on failure. The memory
94 * returned is zeroed. Free it with free_locked_pages.
95 * @param length requested allocation in bytes
96 */
97 void* allocate_locked_pages(size_t length);
98 
99 /**
100 * Free memory allocated by allocate_locked_pages
101 * @param ptr a pointer returned by allocate_locked_pages
102 * @param length length passed to allocate_locked_pages
103 */
104 void free_locked_pages(void* ptr, size_t length);
105 
106 /**
107 * Run a probe instruction to test for support for a CPU instruction.
108 * Runs in system-specific env that catches illegal instructions; this
109 * function always fails if the OS doesn't provide this.
110 * Returns value of probe_fn, if it could run.
111 * If error occurs, returns negative number.
112 * This allows probe_fn to indicate errors of its own, if it wants.
113 * For example the instruction might not only be only available on some
114 * CPUs, but also buggy on some subset of these - the probe function
115 * can test to make sure the instruction works properly before
116 * indicating that the instruction is available.
117 *
118 * @warning on Unix systems uses signal handling in a way that is not
119 * thread safe. It should only be called in a single-threaded context
120 * (ie, at static init time).
121 *
122 * If probe_fn throws an exception the result is undefined.
123 *
124 * Return codes:
125 * -1 illegal instruction detected
126 */
127 int BOTAN_TEST_API run_cpu_instruction_probe(std::function<int ()> probe_fn);
128 
129 /**
130 * Represents a terminal state
131 */
133  {
134  public:
135  /**
136  * Reenable echo on this terminal. Can be safely called
137  * multiple times. May throw if an error occurs.
138  */
139  virtual void reenable_echo() = 0;
140 
141  /**
142  * Implicitly calls reenable_echo, but swallows/ignored all
143  * errors which would leave the terminal in an invalid state.
144  */
145  virtual ~Echo_Suppression() = default;
146  };
147 
148 /**
149 * Suppress echo on the terminal
150 * Returns null if this operation is not supported on the current system.
151 */
152 std::unique_ptr<Echo_Suppression> BOTAN_UNSTABLE_API suppress_echo_on_terminal();
153 
154 }
155 
156 }
157 
158 #endif
#define BOTAN_UNSTABLE_API
Definition: compiler.h:38
int BOTAN_TEST_API run_cpu_instruction_probe(std::function< int()> probe_fn)
Definition: os_utils.cpp:420
uint64_t BOTAN_TEST_API get_cpu_cycle_counter()
Definition: os_utils.cpp:104
uint32_t BOTAN_TEST_API get_process_id()
Definition: os_utils.cpp:80
void * allocate_locked_pages(size_t length)
Definition: os_utils.cpp:336
#define BOTAN_TEST_API
Definition: compiler.h:45
size_t get_memory_locking_limit()
Definition: os_utils.cpp:250
bool running_in_privileged_state()
Definition: os_utils.cpp:93
uint64_t BOTAN_TEST_API get_system_timestamp_ns()
Definition: os_utils.cpp:217
Definition: alg_id.cpp:13
std::unique_ptr< Echo_Suppression > BOTAN_UNSTABLE_API suppress_echo_on_terminal()
Definition: os_utils.cpp:475
size_t system_page_size()
Definition: os_utils.cpp:231
const char * read_env_variable(const std::string &var_name)
Definition: os_utils.cpp:328
void free_locked_pages(void *ptr, size_t length)
Definition: os_utils.cpp:384
uint64_t BOTAN_TEST_API get_high_resolution_clock()
Definition: os_utils.cpp:165