1=============== 2Hardening Modes 3=============== 4 5.. contents:: 6 :local: 7 8.. _using-hardening-modes: 9 10Using hardening modes 11===================== 12 13libc++ provides several hardening modes, where each mode enables a set of 14assertions that prevent undefined behavior caused by violating preconditions of 15the standard library. Different hardening modes make different trade-offs 16between the amount of checking and runtime performance. The available hardening 17modes are: 18- fast mode; 19- extensive mode; 20- debug mode. 21 22The fast mode contains a set of security-critical checks that can be done with 23relatively little overhead in constant time and are intended to be used in 24production. We recommend most projects to adopt the fast mode. 25 26The extensive mode contains all the checks from the fast mode and additionally 27some checks for undefined behavior that incur relatively little overhead but 28aren't security-critical. While the performance penalty is somewhat more 29significant compared to the fast mode, the extensive mode is still intended to 30be usable in production. 31 32The debug mode enables all the available checks in the library, including 33internal assertions, some of which might be very expensive. This mode is 34intended to be used for testing, not in production. 35 36Vendors can set the default hardening mode by using the 37``LIBCXX_HARDENING_MODE`` variable at CMake configuration time with the possible 38values of ``none``, ``fast``, ``extensive`` and ``debug``. The default value is 39``none`` which doesn't enable any hardening checks (this mode is sometimes 40called the ``unchecked`` mode). 41 42When hardening is enabled, the compiled library is built with the corresponding 43mode enabled, **and** user code will be built with the same mode enabled by 44default. If the mode is set to "none" at the CMake configuration time, the 45compiled library will not contain any assertions and the default when building 46user code will be to have assertions disabled. As a user, you can consult your 47vendor to know which level of hardening is enabled by default. 48 49Furthermore, independently of any vendor-selected default, users can always 50control which level of hardening is enabled in their code by defining the macro 51``_LIBCPP_HARDENING_MODE`` before including any libc++ headers (preferably by 52passing ``-D_LIBCPP_HARDENING_MODE=X`` to the compiler). The macro can be 53set to one of the following possible values: 54 55- ``_LIBCPP_HARDENING_MODE_NONE``; 56- ``_LIBCPP_HARDENING_MODE_FAST``; 57- ``_LIBCPP_HARDENING_MODE_EXTENSIVE``; 58- ``_LIBCPP_HARDENING_MODE_DEBUG``. 59 60The exact numeric values of these macros are unspecified and users should not 61rely on them (e.g. expect the values to be sorted in any way). 62 63Note that if the compiled library was built by the vendor with the hardening 64mode set to "none", functions compiled inside the static or shared library won't 65have any hardening enabled even if the user compiles with hardening enabled (the 66same is true for the inverse case where the static or shared library was 67compiled **with** hardening enabled but the user tries to disable it). However, 68most of the code in libc++ is in the headers, so the user-selected value for 69``_LIBCPP_HARDENING_MODE``, if any, will usually be respected. 70 71Enabling hardening has no impact on the ABI. 72 73Iterator bounds checking 74------------------------ 75TODO(hardening) 76