diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ClangFormatStyleOptions.rst | 38 | ||||
| -rw-r--r-- | docs/ControlFlowIntegrity.rst | 4 | ||||
| -rw-r--r-- | docs/LanguageExtensions.rst | 3 | ||||
| -rw-r--r-- | docs/Modules.rst | 11 | ||||
| -rw-r--r-- | docs/SafeStack.rst | 163 | ||||
| -rw-r--r-- | docs/UsersManual.rst | 60 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/tools/clang.pod | 14 |
8 files changed, 240 insertions, 54 deletions
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index c06a8c7..f4c4c8c 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -155,23 +155,21 @@ the configuration (without a prefix: ``Auto``). This applies to round brackets (parentheses), angle brackets and square brackets. This will result in formattings like - - .. code-block:: c++ - - someLongFunction(argument1, - argument2); + \code + someLongFunction(argument1, + argument2); + \endcode **AlignConsecutiveAssignments** (``bool``) If ``true``, aligns consecutive assignments. This will align the assignment operators of consecutive lines. This will result in formattings like - - .. code-block:: c++ - - int aaaa = 12; - int b = 23; - int ccc = 23; + \code + int aaaa = 12; + int b = 23; + int ccc = 23; + \endcode **AlignEscapedNewlinesLeft** (``bool``) If ``true``, aligns escaped newlines as far left as possible. @@ -204,10 +202,10 @@ the configuration (without a prefix: ``Auto``). * ``SFS_None`` (in configuration: ``None``) Never merge functions into a single line. - * ``SFS_Inline`` (in configuration: ``Inline``) - Only merge functions defined inside a class. * ``SFS_Empty`` (in configuration: ``Empty``) Only merge empty functions. + * ``SFS_Inline`` (in configuration: ``Inline``) + Only merge functions defined inside a class. Implies "empty". * ``SFS_All`` (in configuration: ``All``) Merge all functions fitting on a single line. @@ -230,6 +228,11 @@ the configuration (without a prefix: ``Auto``). **AlwaysBreakBeforeMultilineStrings** (``bool``) If ``true``, always break before multiline string literals. + This flag is mean to make cases where there are multiple multiline strings + in a file look more consistent. Thus, it will only take effect if wrapping + the string at that point leads to it being indented + ``ContinuationIndentWidth`` spaces from the start of the line. + **AlwaysBreakTemplateDeclarations** (``bool``) If ``true``, always break after the ``template<...>`` of a template declaration. @@ -343,11 +346,10 @@ the configuration (without a prefix: ``Auto``). instead of as function calls. These are expected to be macros of the form: - - .. code-block:: c++ - - FOREACH(<variable-declaration>, ...) - <loop-body> + \code + FOREACH(<variable-declaration>, ...) + <loop-body> + \endcode For example: BOOST_FOREACH. diff --git a/docs/ControlFlowIntegrity.rst b/docs/ControlFlowIntegrity.rst index 915385b..ce1c37b 100644 --- a/docs/ControlFlowIntegrity.rst +++ b/docs/ControlFlowIntegrity.rst @@ -20,8 +20,8 @@ program's control flow. These schemes have been optimized for performance, allowing developers to enable them in release builds. To enable Clang's available CFI schemes, use the flag ``-fsanitize=cfi``. -As currently implemented, CFI relies on link-time optimization (LTO); the CFI -schemes imply ``-flto``, and the linker used must support LTO, for example +As currently implemented, CFI relies on link-time optimization (LTO); so it is +required to specify ``-flto``, and the linker used must support LTO, for example via the `gold plugin`_. To allow the checks to be implemented efficiently, the program must be structured such that certain object files are compiled with CFI enabled, and are statically linked into the program. This may diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index bd5992e..0b4775b 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -1845,6 +1845,9 @@ with :doc:`ThreadSanitizer`. Use ``__has_feature(memory_sanitizer)`` to check if the code is being built with :doc:`MemorySanitizer`. +Use ``__has_feature(safe_stack)`` to check if the code is being built +with :doc:`SafeStack`. + Extensions for selectively disabling optimization ================================================= diff --git a/docs/Modules.rst b/docs/Modules.rst index 9999106..1f3d898 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -159,7 +159,7 @@ Module maps are specified as separate files (each named ``module.modulemap``) al To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section `Modularizing a Platform`_ describes the steps one must take to write these module maps. -One can use module maps without modules to check the integrity of the use of header files. To do this, use the ``-fmodule-maps`` option instead of the ``-fmodules`` option. +One can use module maps without modules to check the integrity of the use of header files. To do this, use the ``-fimplicit-module-maps`` option instead of the ``-fmodules`` option, or use ``-fmodule-map-file=`` option to explicitly specify the module map files to load. Compilation model ----------------- @@ -174,8 +174,8 @@ Command-line parameters ``-fmodules`` Enable the modules feature. -``-fmodule-maps`` - Enable interpretation of module maps. This option is implied by ``-fmodules``. +``-fimplicit-module-maps`` + Enable implicit search for module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. If this is disabled with ``-fno-implicit-module-maps``, module map files will only be loaded if they are explicitly specified via ``-fmodule-map-file`` or transitively used by another module map file. ``-fmodules-cache-path=<directory>`` Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default. @@ -207,9 +207,6 @@ Command-line parameters ``-fmodules-search-all`` If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion. -``-fno-modules-implicit-maps`` - Suppresses the implicit search for files called ``module.modulemap`` and similar. Instead, module files need to be explicitly specified via ``-fmodule-map-file`` or transitively used. - ``-fno-implicit-modules`` All modules used by the build must be specified with ``-fmodule-file``. @@ -682,7 +679,7 @@ A *link-declaration* with the ``framework`` specifies that the linker should lin Configuration macros declaration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The *config-macros-declaration* specifies the set of configuration macros that have an effect on the the API of the enclosing module. +The *config-macros-declaration* specifies the set of configuration macros that have an effect on the API of the enclosing module. .. parsed-literal:: diff --git a/docs/SafeStack.rst b/docs/SafeStack.rst new file mode 100644 index 0000000..5115d95 --- /dev/null +++ b/docs/SafeStack.rst @@ -0,0 +1,163 @@ +========= +SafeStack +========= + +.. contents:: + :local: + +Introduction +============ + +SafeStack is an instrumentation pass that protects programs against attacks +based on stack buffer overflows, without introducing any measurable performance +overhead. It works by separating the program stack into two distinct regions: +the safe stack and the unsafe stack. The safe stack stores return addresses, +register spills, and local variables that are always accessed in a safe way, +while the unsafe stack stores everything else. This separation ensures that +buffer overflows on the unsafe stack cannot be used to overwrite anything +on the safe stack, which includes return addresses. + +Performance +----------- + +The performance overhead of the SafeStack instrumentation is less than 0.1% on +average across a variety of benchmarks (see the `Code-Pointer Integrity +<http://dslab.epfl.ch/pubs/cpi.pdf>`_ paper for details). This is mainly +because most small functions do not have any variables that require the unsafe +stack and, hence, do not need unsafe stack frames to be created. The cost of +creating unsafe stack frames for large functions is amortized by the cost of +executing the function. + +In some cases, SafeStack actually improves the performance. Objects that end up +being moved to the unsafe stack are usually large arrays or variables that are +used through multiple stack frames. Moving such objects away from the safe +stack increases the locality of frequently accessed values on the stack, such +as register spills, return addresses, and small local variables. + +Limitations +----------- + +SafeStack has not been subjected to a comprehensive security review, and there +exist known weaknesses, including but not limited to the following. + +In its current state, the separation of local variables provides protection +against stack buffer overflows, but the safe stack itself is not protected +from being corrupted through a pointer dereference. The Code-Pointer +Integrity paper describes two ways in which we may protect the safe stack: +hardware segmentation on the 32-bit x86 architecture or information hiding +on other architectures. + +Even with information hiding, the safe stack would merely be hidden +from attackers by being somewhere in the address space. Depending on the +application, the address could be predictable even on 64-bit address spaces +because not all the bits are addressable, multiple threads each have their +stack, the application could leak the safe stack address to memory via +``__builtin_frame_address``, bugs in the low-level runtime support etc. +Safe stack leaks could be mitigated by writing and deploying a static binary +analysis or a dynamic binary instrumentation based tool to find leaks. + +This approach doesn't prevent an attacker from "imbalancing" the safe +stack by say having just one call, and doing two rets (thereby returning +to an address that wasn't meant as a return address). This can be at least +partially mitigated by deploying SafeStack alongside a forward control-flow +integrity mechanism to ensure that calls are made using the correct calling +convention. Clang does not currently implement a comprehensive forward +control-flow integrity protection scheme; there exists one that protects +:doc:`virtual calls <ControlFlowIntegrity>` but not non-virtual indirect calls. + +Compatibility +------------- + +Most programs, static libraries, or individual files can be compiled +with SafeStack as is. SafeStack requires basic runtime support, which, on most +platforms, is implemented as a compiler-rt library that is automatically linked +in when the program is compiled with SafeStack. + +Linking a DSO with SafeStack is not currently supported. + +Known compatibility limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Certain code that relies on low-level stack manipulations requires adaption to +work with SafeStack. One example is mark-and-sweep garbage collection +implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be +changed to look for the live pointers on both safe and unsafe stacks. + +SafeStack supports linking together modules that are compiled with and without +SafeStack, both statically and dynamically. One corner case that is not +supported is using ``dlopen()`` to load a dynamic library that uses SafeStack into +a program that is not compiled with SafeStack but uses threads. + +Signal handlers that use ``sigaltstack()`` must not use the unsafe stack (see +``__attribute__((no_sanitize("safe-stack")))`` below). + +Programs that use APIs from ``ucontext.h`` are not supported yet. + +Usage +===== + +To enable SafeStack, just pass ``-fsanitize=safe-stack`` flag to both compile and link +command lines. + +Supported Platforms +------------------- + +SafeStack was tested on Linux, FreeBSD and MacOSX. + +Low-level API +------------- + +``__has_feature(safe_stack)`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In some rare cases one may need to execute different code depending on +whether SafeStack is enabled. The macro ``__has_feature(safe_stack)`` can +be used for this purpose. + +.. code-block:: c + + #if __has_feature(safe_stack) + // code that builds only under SafeStack + #endif + +``__attribute__((no_sanitize("safe-stack")))`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use ``__attribute__((no_sanitize("safe-stack")))`` on a function declaration +to specify that the safe stack instrumentation should not be applied to that +function, even if enabled globally (see ``-fsanitize=safe-stack`` flag). This +attribute may be required for functions that make assumptions about the +exact layout of their stack frames. + +Care should be taken when using this attribute. The return address is not +protected against stack buffer overflows, and it is easier to leak the +address of the safe stack to memory by taking the address of a local variable. + + +``__builtin___get_unsafe_stack_ptr()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This builtin function returns current unsafe stack pointer of the current +thread. + +``__builtin___get_unsafe_stack_start()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This builtin function returns a pointer to the start of the unsafe stack of the +current thread. + +Design +====== + +Please refer to +`http://dslab.epfl.ch/proj/cpi/ <http://dslab.epfl.ch/proj/cpi/>`_ for more +information about the design of the SafeStack and its related technologies. + + +Publications +------------ + +`Code-Pointer Integrity <http://dslab.epfl.ch/pubs/cpi.pdf>`_. +Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song. +USENIX Symposium on Operating Systems Design and Implementation +(`OSDI <https://www.usenix.org/conference/osdi14>`_), Broomfield, CO, October 2014 diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 2ddf082..cd1b2b3 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -970,16 +970,15 @@ are listed below. includes all of the checks listed below other than ``unsigned-integer-overflow``. - - ``-fsanitize=undefined-trap``: This includes all sanitizers - included by ``-fsanitize=undefined``, except those that require - runtime support. This group of sanitizers is intended to be - used in conjunction with the ``-fsanitize-undefined-trap-on-error`` - flag. This includes all of the checks listed below other than - ``unsigned-integer-overflow`` and ``vptr``. + - ``-fsanitize=undefined-trap``: This is a deprecated alias for + ``-fsanitize=undefined``. + - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data flow analysis. - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>` - checks. Implies ``-flto``. + checks. Requires ``-flto``. + - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>` + protection against stack-based memory corruption errors. The following more fine-grained checks are also available: @@ -992,13 +991,13 @@ are listed below. - ``-fsanitize=cfi-cast-strict``: Enables :ref:`strict cast checks <cfi-strictness>`. - ``-fsanitize=cfi-derived-cast``: Base-to-derived cast to the wrong - dynamic type. Implies ``-flto``. + dynamic type. Requires ``-flto``. - ``-fsanitize=cfi-unrelated-cast``: Cast from ``void*`` or another - unrelated type to the wrong dynamic type. Implies ``-flto``. + unrelated type to the wrong dynamic type. Requires ``-flto``. - ``-fsanitize=cfi-nvcall``: Non-virtual call via an object whose vptr is of - the wrong dynamic type. Implies ``-flto``. + the wrong dynamic type. Requires ``-flto``. - ``-fsanitize=cfi-vcall``: Virtual call via an object whose vptr is of the - wrong dynamic type. Implies ``-flto``. + wrong dynamic type. Requires ``-flto``. - ``-fsanitize=enum``: Load of a value of an enumerated type which is not in the range of representable values for that enumerated type. @@ -1067,15 +1066,6 @@ are listed below. through. This mode may use extra memory in programs that copy uninitialized memory a lot. - Extra features of UndefinedBehaviorSanitizer: - - - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted - rather than calls to runtime libraries when a problem is detected. - This option is intended for use in cases where the sanitizer runtime - cannot be used (for instance, when building libc or a kernel module). - This is only compatible with the sanitizers in the ``undefined-trap`` - group. - The ``-fsanitize=`` argument must also be provided when linking, in order to link to the appropriate runtime library. When using ``-fsanitize=vptr`` (or a group that includes it, such as @@ -1099,11 +1089,41 @@ are listed below. sanitizers (e.g. :doc:`AddressSanitizer`) may not support recovery, and always crash the program after the issue is detected. + Note that the ``-fsanitize-trap`` flag has precedence over this flag. + This means that if a check has been configured to trap elsewhere on the + command line, or if the check traps by default, this flag will not have + any effect unless that sanitizer's trapping behavior is disabled with + ``-fno-sanitize-trap``. + + For example, if a command line contains the flags ``-fsanitize=undefined + -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment`` + will have no effect on its own; it will need to be accompanied by + ``-fno-sanitize-trap=alignment``. + +**-f[no-]sanitize-trap=check1,check2,...** + + Controls which checks enabled by the ``-fsanitize=`` flag trap. This + option is intended for use in cases where the sanitizer runtime cannot + be used (for instance, when building libc or a kernel module), or where + the binary size increase caused by the sanitizer runtime is a concern. + + This flag is only compatible with ``local-bounds``, + ``unsigned-integer-overflow``, sanitizers in the ``cfi`` group and + sanitizers in the ``undefined`` group other than ``vptr``. If this flag + is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer + will be implicitly disabled. + + This flag is enabled by default for sanitizers in the ``cfi`` group. + **-f[no-]sanitize-coverage=[type,features,...]** Enable simple code coverage in addition to certain sanitizers. See :doc:`SanitizerCoverage` for more details. +.. option:: -fsanitize-undefined-trap-on-error + + Deprecated alias for ``-fsanitize-trap=undefined``. + .. option:: -fno-assume-sane-operator-new Don't assume that the C++'s new operator is sane. diff --git a/docs/index.rst b/docs/index.rst index a3c8ffb..dec2bc8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,7 @@ Using Clang as a Compiler SanitizerCoverage SanitizerSpecialCaseList ControlFlowIntegrity + SafeStack Modules MSVCCompatibility FAQ diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod index f7d2eaf..153f97b 100644 --- a/docs/tools/clang.pod +++ b/docs/tools/clang.pod @@ -39,12 +39,12 @@ the other tools. This stage handles tokenization of the input source file, macro expansion, #include expansion and handling of other preprocessor directives. The output of this stage is typically called a ".i" (for C), ".ii" (for C++), ".mi" (for -Objective-C) , or ".mii" (for Objective-C++) file. +Objective-C), or ".mii" (for Objective-C++) file. =item B<Parsing and Semantic Analysis> This stage parses the input file, translating preprocessor tokens into a parse -tree. Once in the form of a parser tree, it applies semantic analysis to compute +tree. Once in the form of a parse tree, it applies semantic analysis to compute types for expressions as well and determine whether the code is well formed. This stage is responsible for generating most of the compiler warnings as well as parse errors. The output of this stage is an "Abstract Syntax Tree" (AST). @@ -330,13 +330,13 @@ all by the program. =item B<-fexceptions> -Enable generation of unwind information, this allows exceptions to be thrown +Enable generation of unwind information. This allows exceptions to be thrown through Clang compiled stack frames. This is on by default in x86-64. =item B<-ftrapv> Generate code to catch integer overflow errors. Signed integer overflow is -undefined in C, with this flag, extra code is generated to detect this and abort +undefined in C. With this flag, extra code is generated to detect this and abort when it happens. @@ -389,7 +389,7 @@ Display available options. =item B<-Qunused-arguments> -Don't emit warning for unused driver arguments. +Do not emit any warnings for unused driver arguments. =item B<-Wa,>I<args> @@ -578,7 +578,7 @@ write temporary files used during the compilation process. If this environment variable is present, it is treated as a delimited list of paths to be added to the default system include path list. The -delimiter is the platform dependent delimitor, as used in the I<PATH> +delimiter is the platform dependent delimiter, as used in the I<PATH> environment variable. Empty components in the environment variable are ignored. @@ -592,7 +592,7 @@ which are only used when processing the appropriate language. =item B<MACOSX_DEPLOYMENT_TARGET> If -mmacosx-version-min is unspecified, the default deployment target -is read from this environment variable. This option only affects darwin +is read from this environment variable. This option only affects Darwin targets. =back |
