mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-25 19:26:06 +00:00
89 lines
3.5 KiB
ReStructuredText
89 lines
3.5 KiB
ReStructuredText
.. _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)
|