| .. _hardening-modes: |
| |
| =============== |
| Hardening Modes |
| =============== |
| |
| .. contents:: |
| :local: |
| |
| .. _using-hardening-modes: |
| |
| Using hardening modes |
| ===================== |
| |
| libc++ provides several hardening modes, where each mode enables a set of |
| assertions that prevent undefined behavior caused by violating preconditions of |
| the standard library. Different hardening modes make different trade-offs |
| between the amount of checking and runtime performance. The available hardening |
| modes are: |
| |
| - **Unchecked mode/none**, which disables all hardening checks. |
| - **Fast mode**, which contains a set of security-critical checks that can be |
| done with relatively little overhead in constant time and are intended to be |
| used in production. We recommend most projects adopt this. |
| - **Extensive mode**, which contains all the checks from fast mode and some |
| additional checks for undefined behavior that incur relatively little overhead |
| but aren't security-critical. Production builds requiring a broader set of |
| checks than fast mode should consider enabling extensive mode. The additional |
| rigour impacts performance more than fast mode: we recommend benchmarking to |
| determine if that is acceptable for your program. |
| - **Debug mode**, which enables all the available checks in the library, |
| including internal assertions, some of which might be very expensive. This |
| mode is intended to be used for testing, not in production. |
| |
| .. note:: |
| |
| Enabling hardening has no impact on the ABI. |
| |
| Notes for users |
| --------------- |
| |
| As a libc++ user, consult with your vendor to determine the level of hardening |
| enabled by default. |
| |
| Users wishing for a different hardening level to their vendor default are able |
| to control the level by passing **one** of the following options to the compiler: |
| |
| - ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_NONE`` |
| - ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST`` |
| - ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE`` |
| - ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG`` |
| |
| .. warning:: |
| |
| The exact numeric values of these macros are unspecified and users should not |
| rely on them (e.g. expect the values to be sorted in any way). |
| |
| .. warning:: |
| |
| If you would prefer to override the hardening level on a per-translation-unit |
| basis, you must do so **before** including any headers to avoid `ODR issues`_. |
| |
| .. _`ODR issues`: https://en.cppreference.com/w/cpp/language/definition#:~:text=is%20ill%2Dformed.-,One%20Definition%20Rule,-Only%20one%20definition |
| |
| .. note:: |
| |
| Since the static and shared library components of libc++ are built by the |
| vendor, setting this macro will have no impact on the hardening mode for the |
| pre-built components. Most libc++ code is header-based, so a user-provided |
| value for ``_LIBCPP_HARDENING_MODE`` will be mostly respected. |
| |
| Notes for vendors |
| ----------------- |
| |
| Vendors can set the default hardening mode by providing ``LIBCXX_HARDENING_MODE`` |
| as a configuration option, with the possible values of ``none``, ``fast``, |
| ``extensive`` and ``debug``. The default value is ``none`` which doesn't enable |
| any hardening checks (this mode is sometimes called the ``unchecked`` mode). |
| |
| This option controls both the hardening mode that the precompiled library is |
| built with and the default hardening mode that users will build with. If set to |
| ``none``, the precompiled library will not contain any assertions, and user code |
| will default to building without assertions. |
| |
| Iterator bounds checking |
| ------------------------ |
| |
| TODO(hardening) |