libcxx/docs/Hardening.rst

   1 ===============
   2 Hardening Modes
   3 ===============
   4
   5 .. contents::
   6    :local:
   7
   8 .. _using-hardening-modes:
   9
  10 Using hardening modes
  11 =====================
  12
  13 The hardened mode enables a set of security-critical assertions that prevent
  14 undefined behavior caused by violating preconditions of the standard library.
  15 These assertions can be done with relatively little overhead in constant time
  16 and are intended to be used in production.
  17
  18 In addition to the hardened mode, libc++ also provides two other hardening
  19 modes:
  20 - safe mode;
  21 - debug mode.
  22
  23 The safe mode contains all the checks from the hardened mode and additionally
  24 some checks for undefined behavior that incur relatively little overhead but
  25 aren't security-critical. While the performance penalty is somewhat more
  26 significant compared to the hardened mode, the safe mode is still intended to be
  27 usable in production.
  28
  29 The debug mode, in turn, contains all the checks from the safe mode and
  30 additionally more expensive checks that may affect the complexity of algorithms.
  31 The debug mode is intended to be used for testing, not in production.
  32
  33 Vendors can set the default hardening mode by using the
  34 ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time. Setting
  35 ``LIBCXX_HARDENING_MODE`` to ``hardened`` enables the hardened mode, and
  36 similarly setting the variable to ``safe`` enables the safe mode, and to
  37 ``debug`` enables the debug mode. The default value is ``unchecked`` which
  38 doesn't enable any hardening.
  39
  40 When hardening is enabled, the compiled library is built with the corresponding
  41 mode enabled, **and** user code will be built with the same mode enabled by
  42 default. If the mode is set to "unchecked" at the CMake configuration time, the
  43 compiled library will not contain any assertions and the default when building
  44 user code will be to have assertions disabled. As a user, you can consult your
  45 vendor to know which level of hardening is enabled by default.
  46
  47 Furthermore, independently of any vendor-selected default, users can always
  48 control which level of hardening is enabled in their code by defining
  49 ``_LIBCPP_ENABLE_HARDENED_MODE=0|1`` (or ``_LIBCPP_ENABLE_SAFE_MODE=0|1``, or
  50 ``_LIBCPP_ENABLE_DEBUG_MODE=0|1``) before including any libc++ header (we
  51 recommend passing ``-D_LIBCPP_ENABLE_HARDENED_MODE=X``, etc. to the compiler).
  52 Note that if the compiled library was built by the vendor in the unchecked mode,
  53 functions compiled inside the static or shared library won't have any hardening
  54 enabled even if the user compiles with hardening enabled (the same is true for
  55 the inverse case where the static or shared library was compiled **with**
  56 hardening enabled but the user tries to disable it). However, most of the code
  57 in libc++ is in the headers, so the user-selected value for
  58 ``_LIBCPP_ENABLE_HARDENED|SAFE|DEBUG_MODE``, if any, will usually be respected.
  59
  60 Enabling hardening has no impact on the ABI.
  61
  62 Iterator bounds checking
  63 ------------------------
  64 TODO(hardening)