Botan 3.5.0
Crypto and TLS for C&
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#include <vector>
15
16#if defined(BOTAN_TARGET_OS_HAS_THREADS)
17 #include <thread>
18#endif
19
20namespace Botan::OS {
21
22/*
23* This header is internal (not installed) and these functions are not
24* intended to be called by applications. However they are given public
25* visibility (using BOTAN_TEST_API macro) for the tests. This also probably
26* allows them to be overridden by the application on ELF systems, but
27* this hasn't been tested.
28*/
29
30/**
31* @return process ID assigned by the operating system.
32*
33* On Unix and Windows systems, this always returns a result
34*
35* On systems where there is no processes to speak of (for example on baremetal
36* systems or within a unikernel), this function returns zero.
37*/
39
40/**
41* Test if we are currently running with elevated permissions
42* eg setuid, setgid, or with POSIX caps set.
43*/
45
46/**
47* @return CPU processor clock, if available
48*
49* On Windows, calls QueryPerformanceCounter.
50*
51* Under GCC or Clang on supported platforms the hardware cycle counter is queried.
52* Currently supported processors are x86, PPC, Alpha, SPARC, IA-64, S/390x, and HP-PA.
53* If no CPU cycle counter is available on this system, returns zero.
54*/
56
58
59/**
60* Return the ELF auxiliary vector cooresponding to the given ID.
61* This only makes sense on Unix-like systems and is currently
62* only supported on Linux, Android, and FreeBSD.
63*
64* Returns zero if not supported on the current system or if
65* the id provided is not known.
66*/
67unsigned long get_auxval(unsigned long id);
68
69/*
70* @return best resolution timestamp available
71*
72* The epoch and update rate of this clock is arbitrary and depending
73* on the hardware it may not tick at a constant rate.
74*
75* Uses hardware cycle counter, if available.
76* On POSIX platforms clock_gettime is used with a monotonic timer
77* As a final fallback std::chrono::high_resolution_clock is used.
78*/
80
81/**
82* @return system clock (reflecting wall clock) with best resolution
83* available, normalized to nanoseconds resolution.
84*/
86
87/**
88* Format a time
89*
90* Converts the time_t to a local time representation,
91* then invokes std::put_time with the specified format.
92*/
93std::string BOTAN_TEST_API format_time(time_t time, const std::string& format);
94
95/**
96* @return maximum amount of memory (in bytes) Botan could/should
97* hyptothetically allocate for the memory poool. Reads environment
98* variable "BOTAN_MLOCK_POOL_SIZE", set to "0" to disable pool.
99*/
101
102/**
103* Return the size of a memory page, if that can be derived on the
104* current system. Otherwise returns some default value (eg 4096)
105*/
106size_t system_page_size();
107
108/**
109* Read the value of an environment variable, setting it to value_out if it
110* exists. Returns false and sets value_out to empty string if no such variable
111* is set. If the process seems to be running in a privileged state (such as
112* setuid) then always returns false and does not examine the environment.
113*/
114bool read_env_variable(std::string& value_out, std::string_view var_name);
115
116/**
117* Read the value of an environment variable and convert it to an
118* integer. If not set or conversion fails, returns the default value.
119*
120* If the process seems to be running in a privileged state (such as setuid)
121* then always returns nullptr, similiar to glibc's secure_getenv.
122*/
123size_t read_env_variable_sz(std::string_view var_name, size_t def_value = 0);
124
125/**
126* Request count pages of RAM which are locked into memory using mlock,
127* VirtualLock, or some similar OS specific API. Free it with free_locked_pages.
128*
129* Returns an empty list on failure. This function is allowed to return fewer
130* than count pages.
131*
132* The contents of the allocated pages are undefined.
133*
134* Each page is preceded by and followed by a page which is marked
135* as noaccess, such that accessing it will cause a crash. This turns
136* out of bound reads/writes into crash events.
137*
138* @param count requested number of locked pages
139*/
140std::vector<void*> allocate_locked_pages(size_t count);
141
142/**
143* Free memory allocated by allocate_locked_pages
144* @param pages a list of pages returned by allocate_locked_pages
145*/
146void free_locked_pages(const std::vector<void*>& pages);
147
148/**
149* Set the MMU to prohibit access to this page
150*/
151void page_prohibit_access(void* page);
152
153/**
154* Set the MMU to allow R/W access to this page
155*/
156void page_allow_access(void* page);
157
158/**
159* Set a ID to a page's range expressed by size bytes
160*/
161void page_named(void* page, size_t size);
162
163#if defined(BOTAN_TARGET_OS_HAS_THREADS)
164void set_thread_name(std::thread& thread, const std::string& name);
165#endif
166
167/**
168* Run a probe instruction to test for support for a CPU instruction.
169* Runs in system-specific env that catches illegal instructions; this
170* function always fails if the OS doesn't provide this.
171* Returns value of probe_fn, if it could run.
172* If error occurs, returns negative number.
173* This allows probe_fn to indicate errors of its own, if it wants.
174* For example the instruction might not only be only available on some
175* CPUs, but also buggy on some subset of these - the probe function
176* can test to make sure the instruction works properly before
177* indicating that the instruction is available.
178*
179* @warning on Unix systems uses signal handling in a way that is not
180* thread safe. It should only be called in a single-threaded context
181* (ie, at static init time).
182*
183* If probe_fn throws an exception the result is undefined.
184*
185* Return codes:
186* -1 illegal instruction detected
187*/
188int BOTAN_TEST_API run_cpu_instruction_probe(const std::function<int()>& probe_fn);
189
190/**
191* Represents a terminal state
192*/
194 public:
195 /**
196 * Reenable echo on this terminal. Can be safely called
197 * multiple times. May throw if an error occurs.
198 */
199 virtual void reenable_echo() = 0;
200
201 /**
202 * Implicitly calls reenable_echo, but swallows/ignored all
203 * errors which would leave the terminal in an invalid state.
204 */
205 virtual ~Echo_Suppression() = default;
206};
207
208/**
209* Suppress echo on the terminal
210* Returns null if this operation is not supported on the current system.
211*/
212std::unique_ptr<Echo_Suppression> BOTAN_UNSTABLE_API suppress_echo_on_terminal();
213
214} // namespace Botan::OS
215
216#endif
virtual void reenable_echo()=0
virtual ~Echo_Suppression()=default
std::string name
#define BOTAN_UNSTABLE_API
Definition compiler.h:44
#define BOTAN_TEST_API
Definition compiler.h:51
bool running_in_privileged_state()
Definition os_utils.cpp:169
size_t get_memory_locking_limit()
Definition os_utils.cpp:370
uint64_t BOTAN_TEST_API get_high_resolution_clock()
Definition os_utils.cpp:268
size_t BOTAN_TEST_API get_cpu_available()
Definition os_utils.cpp:236
std::unique_ptr< Echo_Suppression > BOTAN_UNSTABLE_API suppress_echo_on_terminal()
Definition os_utils.cpp:745
size_t read_env_variable_sz(std::string_view var_name, size_t def_value=0)
Definition os_utils.cpp:464
void page_allow_access(void *page)
Definition os_utils.cpp:595
std::string BOTAN_TEST_API format_time(time_t time, const std::string &format)
Definition os_utils.cpp:330
bool read_env_variable(std::string &value_out, std::string_view var_name)
Definition os_utils.cpp:431
void page_prohibit_access(void *page)
Definition os_utils.cpp:609
int BOTAN_TEST_API run_cpu_instruction_probe(const std::function< int()> &probe_fn)
Definition os_utils.cpp:705
std::vector< void * > allocate_locked_pages(size_t count)
Definition os_utils.cpp:504
size_t system_page_size()
Definition os_utils.cpp:350
uint64_t BOTAN_TEST_API get_system_timestamp_ns()
Definition os_utils.cpp:318
unsigned long get_auxval(unsigned long id)
Definition os_utils.cpp:130
void free_locked_pages(const std::vector< void * > &pages)
Definition os_utils.cpp:623
void page_named(void *page, size_t size)
Definition os_utils.cpp:645
uint32_t BOTAN_TEST_API get_process_id()
Definition os_utils.cpp:118
uint64_t BOTAN_TEST_API get_cpu_cycle_counter()
Definition os_utils.cpp:179