Classes
class	Echo_Suppression

class	Socket

class	SocketUDP

Functions
std::vector< void * >	allocate_locked_pages (size_t count)

unsigned long	auxval_hwcap ()

unsigned long	auxval_hwcap2 ()

std::string BOTAN_TEST_API	format_time (time_t time, const std::string &format)

void	free_locked_pages (const std::vector< void * > &pages)

unsigned long	get_auxval (unsigned long id)

size_t BOTAN_TEST_API	get_cpu_available ()

uint64_t BOTAN_TEST_API	get_cpu_cycle_counter ()

uint64_t BOTAN_TEST_API	get_high_resolution_clock ()

size_t	get_memory_locking_limit ()

uint32_t BOTAN_TEST_API	get_process_id ()

uint64_t BOTAN_TEST_API	get_system_timestamp_ns ()

bool	has_auxval ()

std::unique_ptr< Socket > BOTAN_TEST_API	open_socket (std::string_view hostname, std::string_view service, std::chrono::milliseconds timeout)

std::unique_ptr< SocketUDP > BOTAN_TEST_API	open_socket_udp (std::string_view hostname, std::string_view service, std::chrono::microseconds timeout)

std::unique_ptr< SocketUDP > BOTAN_TEST_API	open_socket_udp (std::string_view uri, std::chrono::microseconds timeout)

void	page_allow_access (void *page)

void	page_named (void *page, size_t size)

void	page_prohibit_access (void *page)

bool	read_env_variable (std::string &value_out, std::string_view var_name)

size_t	read_env_variable_sz (std::string_view var_name, size_t def_value=0)

int BOTAN_TEST_API	run_cpu_instruction_probe (const std::function< int()> &probe_fn)

bool	running_in_privileged_state ()

std::unique_ptr< Echo_Suppression > BOTAN_UNSTABLE_API	suppress_echo_on_terminal ()

size_t	system_page_size ()

Function Documentation

◆ allocate_locked_pages()

std::vector< void * > Botan::OS::allocate_locked_pages ( size_t count )

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.

Parameters

count requested number of locked pages

Definition at line 515 of file os_utils.cpp.

                                                       {
   std::vector<void*> result;
 
#if(defined(BOTAN_TARGET_OS_HAS_POSIX1) && defined(BOTAN_TARGET_OS_HAS_POSIX_MLOCK)) || \
   defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
 
   result.reserve(count);
 
   const size_t page_size = OS::system_page_size();
 
   #if defined(BOTAN_TARGET_OS_HAS_POSIX1) && defined(BOTAN_TARGET_OS_HAS_POSIX_MLOCK)
   static const int locked_fd = get_locked_fd();
   #endif
 
   for(size_t i = 0; i != count; ++i) {
      void* ptr = nullptr;
 
   #if defined(BOTAN_TARGET_OS_HAS_POSIX1) && defined(BOTAN_TARGET_OS_HAS_POSIX_MLOCK)
 
      int mmap_flags = MAP_PRIVATE;
 
      #if defined(MAP_ANONYMOUS)
      mmap_flags |= MAP_ANONYMOUS;
      #elif defined(MAP_ANON)
      mmap_flags |= MAP_ANON;
      #endif
 
      #if defined(MAP_CONCEAL)
      mmap_flags |= MAP_CONCEAL;
      #elif defined(MAP_NOCORE)
      mmap_flags |= MAP_NOCORE;
      #endif
 
      int mmap_prot = PROT_READ | PROT_WRITE;
 
      #if defined(PROT_MAX)
      mmap_prot |= PROT_MAX(mmap_prot);
      #endif
 
      ptr = ::mmap(nullptr,
                   3 * page_size,
                   mmap_prot,
                   mmap_flags,
                   /*fd=*/locked_fd,
                   /*offset=*/0);
 
      if(ptr == MAP_FAILED) {
         continue;
      }
 
      // lock the data page
      if(::mlock(static_cast<uint8_t*>(ptr) + page_size, page_size) != 0) {
         ::munmap(ptr, 3 * page_size);
         continue;
      }
 
      #if defined(MADV_DONTDUMP)
      // we ignore errors here, as DONTDUMP is just a bonus
      ::madvise(static_cast<uint8_t*>(ptr) + page_size, page_size, MADV_DONTDUMP);
      #endif
 
   #elif defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
      ptr = ::VirtualAlloc(nullptr, 3 * page_size, MEM_RESERVE | MEM_COMMIT, PAGE_READWRITE);
 
      if(ptr == nullptr)
         continue;
 
      if(::VirtualLock(static_cast<uint8_t*>(ptr) + page_size, page_size) == 0) {
         ::VirtualFree(ptr, 0, MEM_RELEASE);
         continue;
      }
   #endif
 
      std::memset(ptr, 0, 3 * page_size);  // zero data page and both guard pages
 
      // Attempts to name the data page
      page_named(ptr, 3 * page_size);
      // Make guard page preceeding the data page
      page_prohibit_access(static_cast<uint8_t*>(ptr));
      // Make guard page following the data page
      page_prohibit_access(static_cast<uint8_t*>(ptr) + 2 * page_size);
 
      result.push_back(static_cast<uint8_t*>(ptr) + page_size);
   }
#else
   BOTAN_UNUSED(count);
#endif
 
   return result;
}

References BOTAN_UNUSED, page_named(), page_prohibit_access(), and system_page_size().

Referenced by Botan::mlock_allocator::mlock_allocator().

◆ auxval_hwcap()

unsigned long Botan::OS::auxval_hwcap ( )

If get_auxval is supported, returns the relevant value for AT_HWCAP

If get_auxval is not supported on this system, arbitrarily returns 0

Definition at line 136 of file os_utils.cpp.

                               {
#if defined(AT_HWCAP)
   return AT_HWCAP;
#else
   // If the value is not defined in a header we can see,
   // but auxval is supported, return the Linux/Android value
   return (OS::has_auxval()) ? 16 : 0;
#endif
}

References has_auxval().

◆ auxval_hwcap2()

unsigned long Botan::OS::auxval_hwcap2 ( )

If get_auxval is supported, returns the relevant value for AT_HWCAP2

If get_auxval is not supported on this system, arbitrarily returns 0

Definition at line 146 of file os_utils.cpp.

                                {
#if defined(AT_HWCAP2)
   return AT_HWCAP2;
#else
   // If the value is not defined in a header we can see,
   // but auxval is supported, return the Linux/Android value
   return (OS::has_auxval()) ? 26 : 0;
#endif
}

References has_auxval().

◆ format_time()

std::string Botan::OS::format_time	(	time_t	time,
		const std::string &	format )

Format a time

Converts the time_t to a local time representation, then invokes std::put_time with the specified format.

Definition at line 341 of file os_utils.cpp.

                                                              {
   std::tm tm;
 
#if defined(BOTAN_TARGET_OS_HAS_WIN32)
   localtime_s(&tm, &time);
#elif defined(BOTAN_TARGET_OS_HAS_POSIX1)
   localtime_r(&time, &tm);
#else
   if(auto tmp = std::localtime(&time)) {
      tm = *tmp;
   } else {
      throw Encoding_Error("Could not convert time_t to localtime");
   }
#endif
 
   std::ostringstream oss;
   oss << std::put_time(&tm, format.c_str());
   return oss.str();
}

◆ free_locked_pages()

void Botan::OS::free_locked_pages ( const std::vector< void * > & pages )

Free memory allocated by allocate_locked_pages

Parameters

pages a list of pages returned by allocate_locked_pages

Definition at line 634 of file os_utils.cpp.

                                                        {
   const size_t page_size = OS::system_page_size();
 
   for(size_t i = 0; i != pages.size(); ++i) {
      void* ptr = pages[i];
 
      secure_scrub_memory(ptr, page_size);
 
      // ptr points to the data page, guard pages are before and after
      page_allow_access(static_cast<uint8_t*>(ptr) - page_size);
      page_allow_access(static_cast<uint8_t*>(ptr) + page_size);
 
#if defined(BOTAN_TARGET_OS_HAS_POSIX1) && defined(BOTAN_TARGET_OS_HAS_POSIX_MLOCK)
      ::munlock(ptr, page_size);
      ::munmap(static_cast<uint8_t*>(ptr) - page_size, 3 * page_size);
#elif defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
      ::VirtualUnlock(ptr, page_size);
      ::VirtualFree(static_cast<uint8_t*>(ptr) - page_size, 0, MEM_RELEASE);
#endif
   }
}

References page_allow_access(), Botan::secure_scrub_memory(), and system_page_size().

Referenced by Botan::mlock_allocator::~mlock_allocator().

◆ get_auxval()

unsigned long Botan::OS::get_auxval ( unsigned long id )

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.

Definition at line 156 of file os_utils.cpp.

                                             {
#if defined(BOTAN_TARGET_OS_HAS_GETAUXVAL)
   return ::getauxval(id);
#elif defined(BOTAN_TARGET_OS_HAS_ELF_AUX_INFO)
   unsigned long auxinfo = 0;
   ::elf_aux_info(static_cast<int>(id), &auxinfo, sizeof(auxinfo));
   return auxinfo;
#elif defined(BOTAN_TARGET_OS_HAS_AUXINFO)
   for(const AuxInfo* auxinfo = static_cast<AuxInfo*>(::_dlauxinfo()); auxinfo != AT_NULL; ++auxinfo) {
      if(id == auxinfo->a_type)
         return auxinfo->a_v;
   }
 
   return 0;
#else
   BOTAN_UNUSED(id);
   return 0;
#endif
}

References BOTAN_UNUSED.

Referenced by running_in_privileged_state().

◆ get_cpu_available()

size_t Botan::OS::get_cpu_available ( )

Definition at line 247 of file os_utils.cpp.

                             {
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
 
   #if defined(_SC_NPROCESSORS_ONLN)
   const long cpu_online = ::sysconf(_SC_NPROCESSORS_ONLN);
   if(cpu_online > 0) {
      return static_cast<size_t>(cpu_online);
   }
   #endif
 
   #if defined(_SC_NPROCESSORS_CONF)
   const long cpu_conf = ::sysconf(_SC_NPROCESSORS_CONF);
   if(cpu_conf > 0) {
      return static_cast<size_t>(cpu_conf);
   }
   #endif
 
#endif
 
#if defined(BOTAN_TARGET_OS_HAS_THREADS)
   // hardware_concurrency is allowed to return 0 if the value is not
   // well defined or not computable.
   const size_t hw_concur = std::thread::hardware_concurrency();
 
   if(hw_concur > 0) {
      return hw_concur;
   }
#endif
 
   return 1;
}

Referenced by Botan::Thread_Pool::Thread_Pool().

◆ get_cpu_cycle_counter()

uint64_t Botan::OS::get_cpu_cycle_counter ( )

Returns: 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.

Definition at line 190 of file os_utils.cpp.

                                   {
   uint64_t rtc = 0;
 
#if defined(BOTAN_TARGET_OS_HAS_WIN32)
   LARGE_INTEGER tv;
   ::QueryPerformanceCounter(&tv);
   rtc = tv.QuadPart;
 
#elif defined(BOTAN_USE_GCC_INLINE_ASM)
 
   #if defined(BOTAN_TARGET_CPU_IS_X86_FAMILY)
 
   if(CPUID::has_rdtsc()) {
      uint32_t rtc_low = 0, rtc_high = 0;
      asm volatile("rdtsc" : "=d"(rtc_high), "=a"(rtc_low));
      rtc = (static_cast<uint64_t>(rtc_high) << 32) | rtc_low;
   }
 
   #elif defined(BOTAN_TARGET_ARCH_IS_PPC64)
 
   for(;;) {
      uint32_t rtc_low = 0, rtc_high = 0, rtc_high2 = 0;
      asm volatile("mftbu %0" : "=r"(rtc_high));
      asm volatile("mftb %0" : "=r"(rtc_low));
      asm volatile("mftbu %0" : "=r"(rtc_high2));
 
      if(rtc_high == rtc_high2) {
         rtc = (static_cast<uint64_t>(rtc_high) << 32) | rtc_low;
         break;
      }
   }
 
   #elif defined(BOTAN_TARGET_ARCH_IS_ALPHA)
   asm volatile("rpcc %0" : "=r"(rtc));
 
      // OpenBSD does not trap access to the %tick register
   #elif defined(BOTAN_TARGET_ARCH_IS_SPARC64) && !defined(BOTAN_TARGET_OS_IS_OPENBSD)
   asm volatile("rd %%tick, %0" : "=r"(rtc));
 
   #elif defined(BOTAN_TARGET_ARCH_IS_IA64)
   asm volatile("mov %0=ar.itc" : "=r"(rtc));
 
   #elif defined(BOTAN_TARGET_ARCH_IS_S390X)
   asm volatile("stck 0(%0)" : : "a"(&rtc) : "memory", "cc");
 
   #elif defined(BOTAN_TARGET_ARCH_IS_HPPA)
   asm volatile("mfctl 16,%0" : "=r"(rtc));  // 64-bit only?
 
   #else
      //#warning "OS::get_cpu_cycle_counter not implemented"
   #endif
 
#endif
 
   return rtc;
}

Referenced by get_high_resolution_clock(), Botan::Timer::start(), and Botan::Timer::stop().

◆ get_high_resolution_clock()

uint64_t Botan::OS::get_high_resolution_clock ( )

Definition at line 279 of file os_utils.cpp.

                                       {
   if(uint64_t cpu_clock = OS::get_cpu_cycle_counter()) {
      return cpu_clock;
   }
 
#if defined(BOTAN_TARGET_OS_IS_EMSCRIPTEN)
   return emscripten_get_now();
#endif
 
   /*
   If we got here either we either don't have an asm instruction
   above, or (for x86) RDTSC is not available at runtime. Try some
   clock_gettimes and return the first one that works, or otherwise
   fall back to std::chrono.
   */
 
#if defined(BOTAN_TARGET_OS_HAS_CLOCK_GETTIME)
 
   // The ordering here is somewhat arbitrary...
   const clockid_t clock_types[] = {
   #if defined(CLOCK_MONOTONIC_HR)
      CLOCK_MONOTONIC_HR,
   #endif
   #if defined(CLOCK_MONOTONIC_RAW)
      CLOCK_MONOTONIC_RAW,
   #endif
   #if defined(CLOCK_MONOTONIC)
      CLOCK_MONOTONIC,
   #endif
   #if defined(CLOCK_PROCESS_CPUTIME_ID)
      CLOCK_PROCESS_CPUTIME_ID,
   #endif
   #if defined(CLOCK_THREAD_CPUTIME_ID)
      CLOCK_THREAD_CPUTIME_ID,
   #endif
   };
 
   for(clockid_t clock : clock_types) {
      struct timespec ts;
      if(::clock_gettime(clock, &ts) == 0) {
         return (static_cast<uint64_t>(ts.tv_sec) * 1000000000) + static_cast<uint64_t>(ts.tv_nsec);
      }
   }
#endif
 
   // Plain C++11 fallback
   auto now = std::chrono::high_resolution_clock::now().time_since_epoch();
   return std::chrono::duration_cast<std::chrono::nanoseconds>(now).count();
}

References get_cpu_cycle_counter().

Referenced by Botan::RandomNumberGenerator::randomize_with_ts_input().

◆ get_memory_locking_limit()

size_t Botan::OS::get_memory_locking_limit ( )

Returns: 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.

Definition at line 381 of file os_utils.cpp.

                                    {
   /*
   * Linux defaults to only 64 KiB of mlockable memory per process (too small)
   * but BSDs offer a small fraction of total RAM (more than we need). Bound the
   * total mlock size to 512 KiB which is enough to run the entire test suite
   * without spilling to non-mlock memory (and thus presumably also enough for
   * many useful programs), but small enough that we should not cause problems
   * even if many processes are mlocking on the same machine.
   */
   const size_t max_locked_kb = 512;
 
   /*
   * If RLIMIT_MEMLOCK is not defined, likely the OS does not support
   * unprivileged mlock calls.
   */
#if defined(RLIMIT_MEMLOCK) && defined(BOTAN_TARGET_OS_HAS_POSIX1) && defined(BOTAN_TARGET_OS_HAS_POSIX_MLOCK)
   const size_t mlock_requested =
      std::min<size_t>(read_env_variable_sz("BOTAN_MLOCK_POOL_SIZE", max_locked_kb), max_locked_kb);
 
   if(mlock_requested > 0) {
      struct ::rlimit limits;
 
      ::getrlimit(RLIMIT_MEMLOCK, &limits);
 
      if(limits.rlim_cur < limits.rlim_max) {
         limits.rlim_cur = limits.rlim_max;
         ::setrlimit(RLIMIT_MEMLOCK, &limits);
         ::getrlimit(RLIMIT_MEMLOCK, &limits);
      }
 
      return std::min<size_t>(limits.rlim_cur, mlock_requested * 1024);
   }
 
#elif defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
   const size_t mlock_requested =
      std::min<size_t>(read_env_variable_sz("BOTAN_MLOCK_POOL_SIZE", max_locked_kb), max_locked_kb);
 
   SIZE_T working_min = 0, working_max = 0;
   if(!::GetProcessWorkingSetSize(::GetCurrentProcess(), &working_min, &working_max)) {
      return 0;
   }
 
   // According to Microsoft MSDN:
   // The maximum number of pages that a process can lock is equal to the number of pages in its minimum working set minus a small overhead
   // In the book "Windows Internals Part 2": the maximum lockable pages are minimum working set size - 8 pages
   // But the information in the book seems to be inaccurate/outdated
   // I've tested this on Windows 8.1 x64, Windows 10 x64 and Windows 7 x86
   // On all three OS the value is 11 instead of 8
   const size_t overhead = OS::system_page_size() * 11;
   if(working_min > overhead) {
      const size_t lockable_bytes = working_min - overhead;
      return std::min<size_t>(lockable_bytes, mlock_requested * 1024);
   }
#else
   // Not supported on this platform
   BOTAN_UNUSED(max_locked_kb);
#endif
 
   return 0;
}

References BOTAN_UNUSED, read_env_variable_sz(), and system_page_size().

Referenced by Botan::mlock_allocator::mlock_allocator().

◆ get_process_id()

uint32_t Botan::OS::get_process_id ( )

Returns: process ID assigned by the operating system.

On Unix and Windows systems, this always returns a result

On systems where there is no processes to speak of (for example on baremetal systems or within a unikernel), this function returns zero.

Definition at line 112 of file os_utils.cpp.

                            {
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
   return ::getpid();
#elif defined(BOTAN_TARGET_OS_HAS_WIN32)
   return ::GetCurrentProcessId();
#elif defined(BOTAN_TARGET_OS_IS_LLVM) || defined(BOTAN_TARGET_OS_IS_NONE)
   return 0;  // truly no meaningful value
#else
   #error "Missing get_process_id"
#endif
}

Referenced by Botan::RandomNumberGenerator::randomize_with_ts_input(), and Botan::Stateful_RNG::reseed_check().

◆ get_system_timestamp_ns()

uint64_t Botan::OS::get_system_timestamp_ns ( )

Returns: system clock (reflecting wall clock) with best resolution available, normalized to nanoseconds resolution.

Definition at line 329 of file os_utils.cpp.

                                     {
#if defined(BOTAN_TARGET_OS_HAS_CLOCK_GETTIME)
   struct timespec ts;
   if(::clock_gettime(CLOCK_REALTIME, &ts) == 0) {
      return (static_cast<uint64_t>(ts.tv_sec) * 1000000000) + static_cast<uint64_t>(ts.tv_nsec);
   }
#endif
 
   auto now = std::chrono::system_clock::now().time_since_epoch();
   return std::chrono::duration_cast<std::chrono::nanoseconds>(now).count();
}

Referenced by Botan::RandomNumberGenerator::randomize_with_ts_input(), Botan::Timer::start(), and Botan::Timer::stop().

◆ has_auxval()

bool Botan::OS::has_auxval ( )

Return true if get_auxval is implemented on this system

Definition at line 124 of file os_utils.cpp.

                    {
#if defined(BOTAN_TARGET_OS_HAS_GETAUXVAL)
   return true;
#elif defined(BOTAN_TARGET_OS_HAS_ELF_AUX_INFO)
   return true;
#elif defined(BOTAN_TARGET_OS_HAS_AUXINFO)
   return true;
#else
   return false;
#endif
}

Referenced by auxval_hwcap(), auxval_hwcap2(), and running_in_privileged_state().

◆ open_socket()

std::unique_ptr< OS::Socket > Botan::OS::open_socket	(	std::string_view	hostname,
		std::string_view	service,
		std::chrono::milliseconds	timeout )

Open up a socket. Will throw on error. Returns null if sockets are not available on this platform.

Definition at line 351 of file socket.cpp.

                                                                           {
#if defined(BOTAN_HAS_BOOST_ASIO)
   return std::make_unique<Asio_Socket>(hostname, service, timeout);
 
#elif defined(BOTAN_TARGET_OS_HAS_SOCKETS) || defined(BOTAN_TARGET_OS_HAS_WINSOCK2)
   return std::make_unique<BSD_Socket>(hostname, service, timeout);
 
#else
   BOTAN_UNUSED(hostname);
   BOTAN_UNUSED(service);
   BOTAN_UNUSED(timeout);
   // No sockets for you
   return std::unique_ptr<Socket>();
#endif
}

References BOTAN_UNUSED.

◆ open_socket_udp() [1/2]

std::unique_ptr< OS::SocketUDP > Botan::OS::open_socket_udp	(	std::string_view	hostname,
		std::string_view	service,
		std::chrono::microseconds	timeout )

Open up a socket. Will throw on error. Returns null if sockets are not available on this platform.

Definition at line 318 of file socket_udp.cpp.

                                                                                  {
#if defined(BOTAN_HAS_BOOST_ASIO)
   return std::make_unique<Asio_SocketUDP>(hostname, service, timeout);
#elif defined(BOTAN_TARGET_OS_HAS_SOCKETS) || defined(BOTAN_TARGET_OS_HAS_WINSOCK2)
   return std::make_unique<BSD_SocketUDP>(hostname, service, timeout);
#else
   BOTAN_UNUSED(hostname);
   BOTAN_UNUSED(service);
   BOTAN_UNUSED(timeout);
   return std::unique_ptr<OS::SocketUDP>();
#endif
}

References BOTAN_UNUSED.

Referenced by Botan::Roughtime::online_request(), and open_socket_udp().

◆ open_socket_udp() [2/2]

std::unique_ptr< OS::SocketUDP > Botan::OS::open_socket_udp	(	std::string_view	uri,
		std::chrono::microseconds	timeout )

Open up a socket. Will throw on error. Returns null if sockets are not available on this platform.

Definition at line 333 of file socket_udp.cpp.

                                                                                                       {
   const auto uri = URI::fromAny(uri_string);
   if(uri.port == 0) {
      throw Invalid_Argument("UDP port not specified");
   }
   return open_socket_udp(uri.host, std::to_string(uri.port), timeout);
}

References Botan::URI::fromAny(), and open_socket_udp().

◆ page_allow_access()

void Botan::OS::page_allow_access ( void * page )

Set the MMU to allow R/W access to this page

Definition at line 606 of file os_utils.cpp.

                                     {
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
   const size_t page_size = OS::system_page_size();
   ::mprotect(page, page_size, PROT_READ | PROT_WRITE);
#elif defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
   const size_t page_size = OS::system_page_size();
   DWORD old_perms = 0;
   ::VirtualProtect(page, page_size, PAGE_READWRITE, &old_perms);
   BOTAN_UNUSED(old_perms);
#else
   BOTAN_UNUSED(page);
#endif
}

References BOTAN_UNUSED, and system_page_size().

Referenced by Botan::Memory_Pool::allocate(), free_locked_pages(), Botan::Sodium::sodium_mprotect_readwrite(), and Botan::Memory_Pool::~Memory_Pool().

◆ page_named()

void Botan::OS::page_named	(	void *	page,
		size_t	size )

Set a ID to a page's range expressed by size bytes

Definition at line 656 of file os_utils.cpp.

                                           {
#if defined(BOTAN_TARGET_OS_HAS_PRCTL) && defined(PR_SET_VMA) && defined(PR_SET_VMA_ANON_NAME)
   static constexpr char name[] = "Botan mlock pool";
   int r = prctl(PR_SET_VMA, PR_SET_VMA_ANON_NAME, reinterpret_cast<uintptr_t>(page), size, name);
   BOTAN_UNUSED(r);
#else
   BOTAN_UNUSED(page, size);
#endif
}

References BOTAN_UNUSED, and name.

Referenced by allocate_locked_pages().

◆ page_prohibit_access()

void Botan::OS::page_prohibit_access ( void * page )

Set the MMU to prohibit access to this page

Definition at line 620 of file os_utils.cpp.

                                        {
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
   const size_t page_size = OS::system_page_size();
   ::mprotect(page, page_size, PROT_NONE);
#elif defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
   const size_t page_size = OS::system_page_size();
   DWORD old_perms = 0;
   ::VirtualProtect(page, page_size, PAGE_NOACCESS, &old_perms);
   BOTAN_UNUSED(old_perms);
#else
   BOTAN_UNUSED(page);
#endif
}

References BOTAN_UNUSED, and system_page_size().

Referenced by allocate_locked_pages(), Botan::Memory_Pool::deallocate(), Botan::Memory_Pool::Memory_Pool(), and Botan::Sodium::sodium_mprotect_noaccess().

◆ read_env_variable()

bool Botan::OS::read_env_variable	(	std::string &	value_out,
		std::string_view	var_name )

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.

Definition at line 442 of file os_utils.cpp.

                                                                         {
   value_out = "";
 
   if(running_in_privileged_state()) {
      return false;
   }
 
#if defined(BOTAN_TARGET_OS_HAS_WIN32) && defined(BOTAN_BUILD_COMPILER_IS_MSVC)
   const std::string name(name_view);
   char val[128] = {0};
   size_t req_size = 0;
   if(getenv_s(&req_size, val, sizeof(val), name.c_str()) == 0) {
      // Microsoft's implementation always writes a terminating \0,
      // and includes it in the reported length of the environment variable
      // if a value exists.
      if(req_size > 0 && val[req_size - 1] == '\0') {
         value_out = std::string(val);
      } else {
         value_out = std::string(val, req_size);
      }
      return true;
   }
#else
   const std::string name(name_view);
   if(const char* val = std::getenv(name.c_str())) {
      value_out = val;
      return true;
   }
#endif
 
   return false;
}

References name, and running_in_privileged_state().

Referenced by Botan_FFI::ffi_error_exception_thrown(), and read_env_variable_sz().

◆ read_env_variable_sz()

size_t Botan::OS::read_env_variable_sz	(	std::string_view	var_name,
		size_t	def_value = 0 )

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.

Definition at line 475 of file os_utils.cpp.

                                                               {
   std::string value;
   if(read_env_variable(value, name) && !value.empty()) {
      try {
         const size_t val = std::stoul(value, nullptr);
         return val;
      } catch(std::exception&) { /* ignore it */
      }
   }
 
   return def;
}

References name, and read_env_variable().

Referenced by get_memory_locking_limit().

◆ run_cpu_instruction_probe()

int Botan::OS::run_cpu_instruction_probe ( const std::function< int()> & probe_fn )

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

Definition at line 716 of file os_utils.cpp.

                                                                    {
   volatile int probe_result = -3;
 
#if defined(BOTAN_TARGET_OS_HAS_POSIX1) && !defined(BOTAN_TARGET_OS_IS_EMSCRIPTEN)
   struct sigaction old_sigaction;
   struct sigaction sigaction;
 
   sigaction.sa_handler = botan_sigill_handler;
   sigemptyset(&sigaction.sa_mask);
   sigaction.sa_flags = 0;
 
   int rc = ::sigaction(SIGILL, &sigaction, &old_sigaction);
 
   if(rc != 0) {
      throw System_Error("run_cpu_instruction_probe sigaction failed", errno);
   }
 
   rc = sigsetjmp(g_sigill_jmp_buf, /*save sigs*/ 1);
 
   if(rc == 0) {
      // first call to sigsetjmp
      probe_result = probe_fn();
   } else if(rc == 1) {
      // non-local return from siglongjmp in signal handler: return error
      probe_result = -1;
   }
 
   // Restore old SIGILL handler, if any
   rc = ::sigaction(SIGILL, &old_sigaction, nullptr);
   if(rc != 0) {
      throw System_Error("run_cpu_instruction_probe sigaction restore failed", errno);
   }
 
#else
   BOTAN_UNUSED(probe_fn);
#endif
 
   return probe_result;
}

References BOTAN_UNUSED.

◆ running_in_privileged_state()

bool Botan::OS::running_in_privileged_state ( )

Test if we are currently running with elevated permissions eg setuid, setgid, or with POSIX caps set.

Definition at line 176 of file os_utils.cpp.

                                     {
#if defined(AT_SECURE)
   if(OS::has_auxval()) {
      return OS::get_auxval(AT_SECURE) != 0;
   }
#endif
 
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
   return (::getuid() != ::geteuid()) || (::getgid() != ::getegid());
#else
   return false;
#endif
}

References get_auxval(), and has_auxval().

Referenced by read_env_variable().

◆ suppress_echo_on_terminal()

std::unique_ptr< OS::Echo_Suppression > Botan::OS::suppress_echo_on_terminal ( )

Suppress echo on the terminal Returns null if this operation is not supported on the current system.

Definition at line 756 of file os_utils.cpp.

                                                                {
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
   class POSIX_Echo_Suppression : public Echo_Suppression {
      public:
         POSIX_Echo_Suppression() {
            m_stdin_fd = fileno(stdin);
            if(::tcgetattr(m_stdin_fd, &m_old_termios) != 0) {
               throw System_Error("Getting terminal status failed", errno);
            }
 
            struct termios noecho_flags = m_old_termios;
            noecho_flags.c_lflag &= ~ECHO;
            noecho_flags.c_lflag |= ECHONL;
 
            if(::tcsetattr(m_stdin_fd, TCSANOW, &noecho_flags) != 0) {
               throw System_Error("Clearing terminal echo bit failed", errno);
            }
         }
 
         void reenable_echo() override {
            if(m_stdin_fd > 0) {
               if(::tcsetattr(m_stdin_fd, TCSANOW, &m_old_termios) != 0) {
                  throw System_Error("Restoring terminal echo bit failed", errno);
               }
               m_stdin_fd = -1;
            }
         }
 
         ~POSIX_Echo_Suppression() override {
            try {
               reenable_echo();
            } catch(...) {}
         }
 
         POSIX_Echo_Suppression(const POSIX_Echo_Suppression& other) = delete;
         POSIX_Echo_Suppression(POSIX_Echo_Suppression&& other) = delete;
         POSIX_Echo_Suppression& operator=(const POSIX_Echo_Suppression& other) = delete;
         POSIX_Echo_Suppression& operator=(POSIX_Echo_Suppression&& other) = delete;
 
      private:
         int m_stdin_fd;
         struct termios m_old_termios;
   };
 
   return std::make_unique<POSIX_Echo_Suppression>();
 
#elif defined(BOTAN_TARGET_OS_HAS_WIN32)
 
   class Win32_Echo_Suppression : public Echo_Suppression {
      public:
         Win32_Echo_Suppression() {
            m_input_handle = ::GetStdHandle(STD_INPUT_HANDLE);
            if(::GetConsoleMode(m_input_handle, &m_console_state) == 0)
               throw System_Error("Getting console mode failed", ::GetLastError());
 
            DWORD new_mode = ENABLE_LINE_INPUT | ENABLE_PROCESSED_INPUT;
            if(::SetConsoleMode(m_input_handle, new_mode) == 0)
               throw System_Error("Setting console mode failed", ::GetLastError());
         }
 
         void reenable_echo() override {
            if(m_input_handle != INVALID_HANDLE_VALUE) {
               if(::SetConsoleMode(m_input_handle, m_console_state) == 0)
                  throw System_Error("Setting console mode failed", ::GetLastError());
               m_input_handle = INVALID_HANDLE_VALUE;
            }
         }
 
         ~Win32_Echo_Suppression() override {
            try {
               reenable_echo();
            } catch(...) {}
         }
 
         Win32_Echo_Suppression(const Win32_Echo_Suppression& other) = delete;
         Win32_Echo_Suppression(Win32_Echo_Suppression&& other) = delete;
         Win32_Echo_Suppression& operator=(const Win32_Echo_Suppression& other) = delete;
         Win32_Echo_Suppression& operator=(Win32_Echo_Suppression&& other) = delete;
 
      private:
         HANDLE m_input_handle;
         DWORD m_console_state;
   };
 
   return std::make_unique<Win32_Echo_Suppression>();
 
#else
 
   // Not supported on this platform, return null
   return nullptr;
#endif
}

◆ system_page_size()

size_t Botan::OS::system_page_size ( )

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

Definition at line 361 of file os_utils.cpp.

                            {
   const size_t default_page_size = 4096;
 
#if defined(BOTAN_TARGET_OS_HAS_POSIX1)
   long p = ::sysconf(_SC_PAGESIZE);
   if(p > 1) {
      return static_cast<size_t>(p);
   } else {
      return default_page_size;
   }
#elif defined(BOTAN_TARGET_OS_HAS_VIRTUAL_LOCK)
   BOTAN_UNUSED(default_page_size);
   SYSTEM_INFO sys_info;
   ::GetSystemInfo(&sys_info);
   return sys_info.dwPageSize;
#else
   return default_page_size;
#endif
}

References BOTAN_UNUSED.

Referenced by allocate_locked_pages(), free_locked_pages(), get_memory_locking_limit(), Botan::mlock_allocator::mlock_allocator(), page_allow_access(), and page_prohibit_access().

Classes

Functions

Function Documentation

◆ allocate_locked_pages()

◆ auxval_hwcap()

◆ auxval_hwcap2()

◆ format_time()

◆ free_locked_pages()

◆ get_auxval()

◆ get_cpu_available()

◆ get_cpu_cycle_counter()

◆ get_high_resolution_clock()

◆ get_memory_locking_limit()

◆ get_process_id()

◆ get_system_timestamp_ns()

◆ has_auxval()

◆ open_socket()

◆ open_socket_udp() [1/2]

◆ open_socket_udp() [2/2]

◆ page_allow_access()

◆ page_named()

◆ page_prohibit_access()

◆ read_env_variable()

◆ read_env_variable_sz()

◆ run_cpu_instruction_probe()

◆ running_in_privileged_state()

◆ suppress_echo_on_terminal()

◆ system_page_size()