1.. _hardening-modes: 2 3=============== 4Hardening Modes 5=============== 6 7.. contents:: 8 :local: 9 10.. _using-hardening-modes: 11 12Using hardening modes 13===================== 14 15libc++ provides several hardening modes, where each mode enables a set of 16assertions that prevent undefined behavior caused by violating preconditions of 17the standard library. Different hardening modes make different trade-offs 18between the amount of checking and runtime performance. The available hardening 19modes are: 20 21- **Unchecked mode/none**, which disables all hardening checks. 22- **Fast mode**, which contains a set of security-critical checks that can be 23 done with relatively little overhead in constant time and are intended to be 24 used in production. We recommend most projects adopt this. 25- **Extensive mode**, which contains all the checks from fast mode and some 26 additional checks for undefined behavior that incur relatively little overhead 27 but aren't security-critical. Production builds requiring a broader set of 28 checks than fast mode should consider enabling extensive mode. The additional 29 rigour impacts performance more than fast mode: we recommend benchmarking to 30 determine if that is acceptable for your program. 31- **Debug mode**, which enables all the available checks in the library, 32 including internal assertions, some of which might be very expensive. This 33 mode is intended to be used for testing, not in production. 34 35.. note:: 36 37 Enabling hardening has no impact on the ABI. 38 39Notes for users 40--------------- 41 42As a libc++ user, consult with your vendor to determine the level of hardening 43enabled by default. 44 45Users wishing for a different hardening level to their vendor default are able 46to control the level by passing **one** of the following options to the compiler: 47 48- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_NONE`` 49- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST`` 50- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE`` 51- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG`` 52 53.. warning:: 54 55 The exact numeric values of these macros are unspecified and users should not 56 rely on them (e.g. expect the values to be sorted in any way). 57 58.. warning:: 59 60 If you would prefer to override the hardening level on a per-translation-unit 61 basis, you must do so **before** including any headers to avoid `ODR issues`_. 62 63.. _`ODR issues`: https://en.cppreference.com/w/cpp/language/definition#:~:text=is%20ill%2Dformed.-,One%20Definition%20Rule,-Only%20one%20definition 64 65.. note:: 66 67 Since the static and shared library components of libc++ are built by the 68 vendor, setting this macro will have no impact on the hardening mode for the 69 pre-built components. Most libc++ code is header-based, so a user-provided 70 value for ``_LIBCPP_HARDENING_MODE`` will be mostly respected. 71 72Notes for vendors 73----------------- 74 75Vendors can set the default hardening mode by providing ``LIBCXX_HARDENING_MODE`` 76as a configuration option, with the possible values of ``none``, ``fast``, 77``extensive`` and ``debug``. The default value is ``none`` which doesn't enable 78any hardening checks (this mode is sometimes called the ``unchecked`` mode). 79 80This option controls both the hardening mode that the precompiled library is 81built with and the default hardening mode that users will build with. If set to 82``none``, the precompiled library will not contain any assertions, and user code 83will default to building without assertions. 84 85Iterator bounds checking 86------------------------ 87 88TODO(hardening) 89