/src/botan/build/include/botan/internal/os_utils.h

Source (jump to first uncovered line)
/*
* OS specific utility functions
* (C) 2015,2016,2017,2018 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_OS_UTILS_H_
#define BOTAN_OS_UTILS_H_

#include <botan/types.h>
#include <functional>
#include <string>
#include <vector>

namespace Botan {

namespace OS {

/*
* This header is internal (not installed) and these functions are not
* intended to be called by applications. However they are given public
* visibility (using BOTAN_TEST_API macro) for the tests. This also probably
* allows them to be overridden by the application on ELF systems, but
* this hasn't been tested.
*/

/**
* @return process ID assigned by the operating system.
* On Unix and Windows systems, this always returns a result
* On IncludeOS it returns 0 since there is no process ID to speak of
* in a unikernel.
*/
uint32_t BOTAN_TEST_API get_process_id();

/**
* Test if we are currently running with elevated permissions
* eg setuid, setgid, or with POSIX caps set.
*/
bool running_in_privileged_state();

/**
* @return CPU processor clock, if available
*
* On Windows, calls QueryPerformanceCounter.
*
* Under GCC or Clang on supported platforms the hardware cycle counter is queried.
* Currently supported processors are x86, PPC, Alpha, SPARC, IA-64, S/390x, and HP-PA.
* If no CPU cycle counter is available on this system, returns zero.
*/
uint64_t BOTAN_TEST_API get_cpu_cycle_counter();

size_t BOTAN_TEST_API get_cpu_available();

/**
* Return the ELF auxiliary vector cooresponding to the given ID.
* This only makes sense on Unix-like systems and is currently
* only supported on Linux, Android, and FreeBSD.
*
* Returns zero if not supported on the current system or if
* the id provided is not known.
*/
unsigned long get_auxval(unsigned long id);

/*
* @return best resolution timestamp available
*
* The epoch and update rate of this clock is arbitrary and depending
* on the hardware it may not tick at a constant rate.
*
* Uses hardware cycle counter, if available.
* On POSIX platforms clock_gettime is used with a monotonic timer
* As a final fallback std::chrono::high_resolution_clock is used.
*/
uint64_t BOTAN_TEST_API get_high_resolution_clock();

/**
* @return system clock (reflecting wall clock) with best resolution
* available, normalized to nanoseconds resolution.
*/
uint64_t BOTAN_TEST_API get_system_timestamp_ns();

/**
* @return maximum amount of memory (in bytes) Botan could/should
* hyptothetically allocate for the memory poool. Reads environment
* variable "BOTAN_MLOCK_POOL_SIZE", set to "0" to disable pool.
*/
size_t get_memory_locking_limit();

/**
* Return the size of a memory page, if that can be derived on the
* current system. Otherwise returns some default value (eg 4096)
*/
size_t system_page_size();

/**
* Return the cache line size of the current processor using some
* OS specific interface, or 0 if not available on this platform.
*/
size_t get_cache_line_size();

/**
* Read the value of an environment variable, setting it to value_out if it
* exists.  Returns false and sets value_out to empty string if no such variable
* is set. If the process seems to be running in a privileged state (such as
* setuid) then always returns false and does not examine the environment.
*/
bool read_env_variable(std::string& value_out, const std::string& var_name);

/**
* Read the value of an environment variable and convert it to an
* integer. If not set or conversion fails, returns the default value.
*
* If the process seems to be running in a privileged state (such as setuid)
* then always returns nullptr, similiar to glibc's secure_getenv.
*/
size_t read_env_variable_sz(const std::string& var_name, size_t def_value = 0);

/**
* Request count pages of RAM which are locked into memory using mlock,
* VirtualLock, or some similar OS specific API. Free it with free_locked_pages.
*
* Returns an empty list on failure. This function is allowed to return fewer
* than count pages.
*
* The contents of the allocated pages are undefined.
*
* Each page is preceded by and followed by a page which is marked
* as noaccess, such that accessing it will cause a crash. This turns
* out of bound reads/writes into crash events.
*
* @param count requested number of locked pages
*/
std::vector<void*> allocate_locked_pages(size_t count);

/**
* Free memory allocated by allocate_locked_pages
* @param pages a list of pages returned by allocate_locked_pages
*/
void free_locked_pages(const std::vector<void*>& pages);

/**
* Set the MMU to prohibit access to this page
*/
void page_prohibit_access(void* page);

/**
* Set the MMU to allow R/W access to this page
*/
void page_allow_access(void* page);

/**
* Set a ID to a page's range expressed by size bytes
*/
void page_named(void* page, size_t size);


/**
* Run a probe instruction to test for support for a CPU instruction.
* Runs in system-specific env that catches illegal instructions; this
* function always fails if the OS doesn't provide this.
* Returns value of probe_fn, if it could run.
* If error occurs, returns negative number.
* This allows probe_fn to indicate errors of its own, if it wants.
* For example the instruction might not only be only available on some
* CPUs, but also buggy on some subset of these - the probe function
* can test to make sure the instruction works properly before
* indicating that the instruction is available.
*
* @warning on Unix systems uses signal handling in a way that is not
* thread safe. It should only be called in a single-threaded context
* (ie, at static init time).
*
* If probe_fn throws an exception the result is undefined.
*
* Return codes:
* -1 illegal instruction detected
*/
int BOTAN_TEST_API run_cpu_instruction_probe(const std::function<int ()>& probe_fn);

/**
* Represents a terminal state
*/
class BOTAN_UNSTABLE_API Echo_Suppression
   {
   public:
      /**
      * Reenable echo on this terminal. Can be safely called
      * multiple times. May throw if an error occurs.
      */
      virtual void reenable_echo() = 0;

      /**
      * Implicitly calls reenable_echo, but swallows/ignored all
      * errors which would leave the terminal in an invalid state.
      */
      virtual ~Echo_Suppression() = default;
   };

/**
* Suppress echo on the terminal
* Returns null if this operation is not supported on the current system.
*/
std::unique_ptr<Echo_Suppression> BOTAN_UNSTABLE_API suppress_echo_on_terminal();

}

}

#endif

Coverage Report

Created: 2022-06-23 06:44

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