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