summaryrefslogtreecommitdiff
path: root/clang/docs/ControlFlowIntegrity.rst
AgeCommit message (Collapse)Author
2025-11-07[clang] Proofread *.rst (#166897)Kazu Hirata
This patch is limited to single-word replacements to fix spelling and/or grammar to ease the review process. Punctuation and markdown fixes are specifically excluded.
2025-04-15Introduce -funique-source-file-names flag.Peter Collingbourne
The purpose of this flag is to allow the compiler to assume that each object file passed to the linker has been compiled using a unique source file name. This is useful for reducing link times when doing ThinLTO in combination with whole-program devirtualization or CFI, as it allows modules without exported symbols to be built with ThinLTO. Reviewers: vitalybuka, teresajohnson Reviewed By: teresajohnson Pull Request: https://github.com/llvm/llvm-project/pull/135728
2025-04-14Minor documentation update.Peter Collingbourne
2025-04-14Fix broken link.Peter Collingbourne
2025-02-06[X86] Extend kCFI with a 3-bit arity indicator (#121070)Scott Constable
Kernel Control Flow Integrity (kCFI) is a feature that hardens indirect calls by comparing a 32-bit hash of the function pointer's type against a hash of the target function's type. If the hashes do not match, the kernel may panic (or log the hash check failure, depending on the kernel's configuration). These hashes are computed at compile time by applying the xxHash64 algorithm to each mangled canonical function (or function pointer) type, then truncating the result to 32 bits. This hash is written into each indirect-callable function header by encoding it as the 32-bit immediate operand to a `MOVri` instruction, e.g.: ``` __cfi_foo: nop nop nop nop nop nop nop nop nop nop nop movl $199571451, %eax # hash of foo's type = 0xBE537FB foo: ... ``` This PR extends x86-based kCFI with a 3-bit arity indicator encoded in the `MOVri` instruction's register (reg) field as follows: | Arity Indicator | Description | Encoding in reg field | | --------------- | --------------- | --------------- | | 0 | 0 parameters | EAX | | 1 | 1 parameter in RDI | ECX | | 2 | 2 parameters in RDI and RSI | EDX | | 3 | 3 parameters in RDI, RSI, and RDX | EBX | | 4 | 4 parameters in RDI, RSI, RDX, and RCX | ESP | | 5 | 5 parameters in RDI, RSI, RDX, RCX, and R8 | EBP | | 6 | 6 parameters in RDI, RSI, RDX, RCX, R8, and R9 | ESI | | 7 | At least one parameter may be passed on the stack | EDI | For example, if `foo` takes 3 register arguments and no stack arguments then the `MOVri` instruction in its kCFI header would instead be written as: ``` movl $199571451, %ebx # hash of foo's type = 0xBE537FB ``` This PR will benefit other CFI approaches that build on kCFI, such as FineIBT. For example, this proposed enhancement to FineIBT must be able to infer (at kernel init time) which registers are live at an indirect call target: https://lkml.org/lkml/2024/9/27/982. If the arity bits are available in the kCFI function header, then this information is trivial to infer. Note that there is another existing PR proposal that includes the 3-bit arity within the existing 32-bit immediate field, which introduces different security properties: https://github.com/llvm/llvm-project/pull/117121.
2023-05-22-fsanitize=function: support CFangrui Song
With D148785, -fsanitize=function no longer uses C++ RTTI objects and therefore can support C. The rationale for reporting errors is C11 6.5.2.2p9: > If the function is defined with a type that is not compatible with the type (of the expression) pointed to by the expression that denotes the called function, the behavior is undefined. The mangled types approach we use does not exactly match the C type compatibility (see `f(callee1)` below). This is probably fine as the rules are unlikely leveraged in practice. In addition, the call is warned by -Wincompatible-function-pointer-types-strict. ``` void callee0(int (*a)[]) {} void callee1(int (*a)[1]) {} void f(void (*fp)(int (*)[])) { fp(0); } int main() { int a[1]; f(callee0); f(callee1); // compatible but flagged by -fsanitize=function, -fsanitize=kcfi, and -Wincompatible-function-pointer-types-strict } ``` Skip indirect call sites of a function type without a prototype to avoid deal with C11 6.5.2.2p6. -fsanitize=kcfi skips such calls as well. Reviewed By: #sanitizers, vitalybuka Differential Revision: https://reviews.llvm.org/D148827
2023-02-08Add CFI integer types normalizationRamon de C Valle
This commit adds a new option (i.e., `-fsanitize-cfi-icall-normalize-integers`) for normalizing integer types as vendor extended types for cross-language LLVM CFI/KCFI support with other languages that can't represent and encode C/C++ integer types. Specifically, integer types are encoded as their defined representations (e.g., 8-bit signed integer, 16-bit signed integer, 32-bit signed integer, ...) for compatibility with languages that define explicitly-sized integer types (e.g., i8, i16, i32, ..., in Rust). ``-fsanitize-cfi-icall-normalize-integers`` is compatible with ``-fsanitize-cfi-icall-generalize-pointers``. This helps with providing cross-language CFI support with the Rust compiler and is an alternative solution for the issue described and alternatives proposed in the RFC https://github.com/rust-lang/rfcs/pull/3296. For more information about LLVM CFI/KCFI and cross-language LLVM CFI/KCFI support for the Rust compiler, see the design document in the tracking issue https://github.com/rust-lang/rust/issues/89653. Relands b1e9ab7438a098a18fecda88fc87ef4ccadfcf1e with fixes. Reviewed By: pcc, samitolvanen Differential Revision: https://reviews.llvm.org/D139395
2023-02-02Revert "Add CFI integer types normalization"Mitch Phillips
This reverts commit b1e9ab7438a098a18fecda88fc87ef4ccadfcf1e. Reason: Looks like it broke the MSan buildbot, more details in the phabricator review: https://reviews.llvm.org/D139395
2023-02-01Add CFI integer types normalizationRamon de C Valle
This commit adds a new option (i.e., `-fsanitize-cfi-icall-normalize-integers`) for normalizing integer types as vendor extended types for cross-language LLVM CFI/KCFI support with other languages that can't represent and encode C/C++ integer types. Specifically, integer types are encoded as their defined representations (e.g., 8-bit signed integer, 16-bit signed integer, 32-bit signed integer, ...) for compatibility with languages that define explicitly-sized integer types (e.g., i8, i16, i32, ..., in Rust). ``-fsanitize-cfi-icall-normalize-integers`` is compatible with ``-fsanitize-cfi-icall-generalize-pointers``. This helps with providing cross-language CFI support with the Rust compiler and is an alternative solution for the issue described and alternatives proposed in the RFC https://github.com/rust-lang/rfcs/pull/3296. For more information about LLVM CFI/KCFI and cross-language LLVM CFI/KCFI support for the Rust compiler, see the design document in the tracking issue https://github.com/rust-lang/rust/issues/89653. Reviewed By: pcc, samitolvanen Differential Revision: https://reviews.llvm.org/D139395
2022-08-24KCFI sanitizerSami Tolvanen
The KCFI sanitizer, enabled with `-fsanitize=kcfi`, implements a forward-edge control flow integrity scheme for indirect calls. It uses a !kcfi_type metadata node to attach a type identifier for each function and injects verification code before indirect calls. Unlike the current CFI schemes implemented in LLVM, KCFI does not require LTO, does not alter function references to point to a jump table, and never breaks function address equality. KCFI is intended to be used in low-level code, such as operating system kernels, where the existing schemes can cause undue complications because of the aforementioned properties. However, unlike the existing schemes, KCFI is limited to validating only function pointers and is not compatible with executable-only memory. KCFI does not provide runtime support, but always traps when a type mismatch is encountered. Users of the scheme are expected to handle the trap. With `-fsanitize=kcfi`, Clang emits a `kcfi` operand bundle to indirect calls, and LLVM lowers this to a known architecture-specific sequence of instructions for each callsite to make runtime patching easier for users who require this functionality. A KCFI type identifier is a 32-bit constant produced by taking the lower half of xxHash64 from a C++ mangled typename. If a program contains indirect calls to assembly functions, they must be manually annotated with the expected type identifiers to prevent errors. To make this easier, Clang generates a weak SHN_ABS `__kcfi_typeid_<function>` symbol for each address-taken function declaration, which can be used to annotate functions in assembly as long as at least one C translation unit linked into the program takes the function address. For example on AArch64, we might have the following code: ``` .c: int f(void); int (*p)(void) = f; p(); .s: .4byte __kcfi_typeid_f .global f f: ... ``` Note that X86 uses a different preamble format for compatibility with Linux kernel tooling. See the comments in `X86AsmPrinter::emitKCFITypeId` for details. As users of KCFI may need to locate trap locations for binary validation and error handling, LLVM can additionally emit the locations of traps to a `.kcfi_traps` section. Similarly to other sanitizers, KCFI checking can be disabled for a function with a `no_sanitize("kcfi")` function attribute. Relands 67504c95494ff05be2a613129110c9bcf17f6c13 with a fix for 32-bit builds. Reviewed By: nickdesaulniers, kees, joaomoreira, MaskRay Differential Revision: https://reviews.llvm.org/D119296
2022-08-24Revert "KCFI sanitizer"Sami Tolvanen
This reverts commit 67504c95494ff05be2a613129110c9bcf17f6c13 as using PointerEmbeddedInt to store 32 bits breaks 32-bit arm builds.
2022-08-24KCFI sanitizerSami Tolvanen
The KCFI sanitizer, enabled with `-fsanitize=kcfi`, implements a forward-edge control flow integrity scheme for indirect calls. It uses a !kcfi_type metadata node to attach a type identifier for each function and injects verification code before indirect calls. Unlike the current CFI schemes implemented in LLVM, KCFI does not require LTO, does not alter function references to point to a jump table, and never breaks function address equality. KCFI is intended to be used in low-level code, such as operating system kernels, where the existing schemes can cause undue complications because of the aforementioned properties. However, unlike the existing schemes, KCFI is limited to validating only function pointers and is not compatible with executable-only memory. KCFI does not provide runtime support, but always traps when a type mismatch is encountered. Users of the scheme are expected to handle the trap. With `-fsanitize=kcfi`, Clang emits a `kcfi` operand bundle to indirect calls, and LLVM lowers this to a known architecture-specific sequence of instructions for each callsite to make runtime patching easier for users who require this functionality. A KCFI type identifier is a 32-bit constant produced by taking the lower half of xxHash64 from a C++ mangled typename. If a program contains indirect calls to assembly functions, they must be manually annotated with the expected type identifiers to prevent errors. To make this easier, Clang generates a weak SHN_ABS `__kcfi_typeid_<function>` symbol for each address-taken function declaration, which can be used to annotate functions in assembly as long as at least one C translation unit linked into the program takes the function address. For example on AArch64, we might have the following code: ``` .c: int f(void); int (*p)(void) = f; p(); .s: .4byte __kcfi_typeid_f .global f f: ... ``` Note that X86 uses a different preamble format for compatibility with Linux kernel tooling. See the comments in `X86AsmPrinter::emitKCFITypeId` for details. As users of KCFI may need to locate trap locations for binary validation and error handling, LLVM can additionally emit the locations of traps to a `.kcfi_traps` section. Similarly to other sanitizers, KCFI checking can be disabled for a function with a `no_sanitize("kcfi")` function attribute. Reviewed By: nickdesaulniers, kees, joaomoreira, MaskRay Differential Revision: https://reviews.llvm.org/D119296
2021-11-15[NFC] Trim trailing whitespace in *.rstShao-Ce SUN
2021-05-04[clang] accept -fsanitize-ignorelist= in addition to -fsanitize-blacklist=Nico Weber
Use that for internal names (including the default ignorelists of the sanitizers). Differential Revision: https://reviews.llvm.org/D101832
2021-03-06[clang] Fix typos in documentation (NFC)Kazu Hirata
2020-10-02[docs] Update ControlFlowIntegrity.rst.Evgenii Stepanov
Expand the list of targets that support cfi-icall. Add ThinLTO everywhere LTO is mentioned. AFAIK all CFI features are supported with ThinLTO. Differential Revision: https://reviews.llvm.org/D87717
2019-08-09cfi-icall: Allow the jump table to be optionally made non-canonical.Peter Collingbourne
The default behavior of Clang's indirect function call checker will replace the address of each CFI-checked function in the output file's symbol table with the address of a jump table entry which will pass CFI checks. We refer to this as making the jump table `canonical`. This property allows code that was not compiled with ``-fsanitize=cfi-icall`` to take a CFI-valid address of a function, but it comes with a couple of caveats that are especially relevant for users of cross-DSO CFI: - There is a performance and code size overhead associated with each exported function, because each such function must have an associated jump table entry, which must be emitted even in the common case where the function is never address-taken anywhere in the program, and must be used even for direct calls between DSOs, in addition to the PLT overhead. - There is no good way to take a CFI-valid address of a function written in assembly or a language not supported by Clang. The reason is that the code generator would need to insert a jump table in order to form a CFI-valid address for assembly functions, but there is no way in general for the code generator to determine the language of the function. This may be possible with LTO in the intra-DSO case, but in the cross-DSO case the only information available is the function declaration. One possible solution is to add a C wrapper for each assembly function, but these wrappers can present a significant maintenance burden for heavy users of assembly in addition to adding runtime overhead. For these reasons, we provide the option of making the jump table non-canonical with the flag ``-fno-sanitize-cfi-canonical-jump-tables``. When the jump table is made non-canonical, symbol table entries point directly to the function body. Any instances of a function's address being taken in C will be replaced with a jump table address. This scheme does have its own caveats, however. It does end up breaking function address equality more aggressively than the default behavior, especially in cross-DSO mode which normally preserves function address equality entirely. Furthermore, it is occasionally necessary for code not compiled with ``-fsanitize=cfi-icall`` to take a function address that is valid for CFI. For example, this is necessary when a function's address is taken by assembly code and then called by CFI-checking C code. The ``__attribute__((cfi_jump_table_canonical))`` attribute may be used to make the jump table entry of a specific function canonical so that the external code will end up taking a address for the function that will pass CFI checks. Fixes PR41972. Differential Revision: https://reviews.llvm.org/D65629 llvm-svn: 368495
2019-01-23[Documentation] Use HTTPS whenever possibleEugene Zelenko
Differential revision: https://reviews.llvm.org/D56946 llvm-svn: 351976
2018-11-04Update our URLs in clang doc to use httpsSylvestre Ledru
llvm-svn: 346101
2018-06-26Implement CFI for indirect calls via a member function pointer.Peter Collingbourne
Similarly to CFI on virtual and indirect calls, this implementation tries to use program type information to make the checks as precise as possible. The basic way that it works is as follows, where `C` is the name of the class being defined or the target of a call and the function type is assumed to be `void()`. For virtual calls: - Attach type metadata to the addresses of function pointers in vtables (not the functions themselves) of type `void (B::*)()` for each `B` that is a recursive dynamic base class of `C`, including `C` itself. This type metadata has an annotation that the type is for virtual calls (to distinguish it from the non-virtual case). - At the call site, check that the computed address of the function pointer in the vtable has type `void (C::*)()`. For non-virtual calls: - Attach type metadata to each non-virtual member function whose address can be taken with a member function pointer. The type of a function in class `C` of type `void()` is each of the types `void (B::*)()` where `B` is a most-base class of `C`. A most-base class of `C` is defined as a recursive base class of `C`, including `C` itself, that does not have any bases. - At the call site, check that the function pointer has one of the types `void (B::*)()` where `B` is a most-base class of `C`. Differential Revision: https://reviews.llvm.org/D47567 llvm-svn: 335569
2018-06-13docs: Add a missing LTO visibility reference.Peter Collingbourne
llvm-svn: 334671
2018-06-13docs: Correct some misstatements in the control flow integrity docs.Peter Collingbourne
These were true at one point but haven't been true for a long time. llvm-svn: 334669
2018-04-12Fix doc typoVlad Tsyrklevich
llvm-svn: 329942
2017-10-31[CFI] Add CFI-icall pointer type generalizationVlad Tsyrklevich
Summary: This change allows generalizing pointers in type signatures used for cfi-icall by enabling the -fsanitize-cfi-icall-generalize-pointers flag. This works by 1) emitting an additional generalized type signature metadata node for functions and 2) llvm.type.test()ing for the generalized type for translation units with the flag specified. This flag is incompatible with -fsanitize-cfi-cross-dso because it would require emitting twice as many type hashes which would increase artifact size. Reviewers: pcc, eugenis Reviewed By: pcc Subscribers: kcc Differential Revision: https://reviews.llvm.org/D39358 llvm-svn: 317044
2017-09-25Allow specifying sanitizers in blacklistsVlad Tsyrklevich
Summary: This is the follow-up patch to D37924. This change refactors clang to use the the newly added section headers in SpecialCaseList to specify which sanitizers blacklists entries should apply to, like so: [cfi-vcall] fun:*bad_vcall* [cfi-derived-cast|cfi-unrelated-cast] fun:*bad_cast* The SanitizerSpecialCaseList class has been added to allow querying by SanitizerMask, and SanitizerBlacklist and its downstream users have been updated to provide that information. Old blacklists not using sections will continue to function identically since the blacklist entries will be placed into a '[*]' section by default matching against all sanitizers. Reviewers: pcc, kcc, eugenis, vsk Reviewed By: eugenis Subscribers: dberris, cfe-commits, mgorny Differential Revision: https://reviews.llvm.org/D37925 llvm-svn: 314171
2016-04-28Re-apply r267784, r267824 and r267830.Peter Collingbourne
I have updated the compiler-rt tests. llvm-svn: 267903
2016-04-28Revert r267784, r267824 and r267830.Benjamin Kramer
It makes compiler-rt tests fail if the gold plugin is enabled. Revert "Rework interface for bitset-using features to use a notion of LTO visibility." Revert "Driver: only produce CFI -fvisibility= error when compiling." Revert "clang/test/CodeGenCXX/cfi-blacklist.cpp: Exclude ms targets. They would be non-cfi." llvm-svn: 267871
2016-04-27Rework interface for bitset-using features to use a notion of LTO visibility.Peter Collingbourne
Bitsets, and the compiler features they rely on (vtable opt, CFI), only have visibility within the LTO'd part of the linkage unit. Therefore, only enable these features for classes with hidden LTO visibility. This notion is based on object file visibility or (on Windows) dllimport/dllexport attributes. We provide the [[clang::lto_visibility_public]] attribute to override the compiler's LTO visibility inference in cases where the class is defined in the non-LTO'd part of the linkage unit, or where the ABI supports calling classes derived from abstract base classes with hidden visibility in other linkage units (e.g. COM on Windows). If the cross-DSO CFI mode is enabled, bitset checks are emitted even for classes with public LTO visibility, as that mode uses a separate mechanism to cause bitsets to be exported. This mechanism replaces the whole-program-vtables blacklist, so remove the -fwhole-program-vtables-blacklist flag. Because __declspec(uuid()) now implies [[clang::lto_visibility_public]], the support for the special attr:uuid blacklist entry is removed. Differential Revision: http://reviews.llvm.org/D18635 llvm-svn: 267784
2016-02-01docs: Clarify that cfi-unrelated-cast is based on lifetime.Peter Collingbourne
Also restore Makefile.sphinx which is needed to build the documentation. llvm-svn: 259382
2015-12-15Cross-DSO control flow integrity (Clang part).Evgeniy Stepanov
Clang-side cross-DSO CFI. * Adds a command line flag -f[no-]sanitize-cfi-cross-dso. * Links a runtime library when enabled. * Emits __cfi_slowpath calls is bitset test fails. * Emits extra hash-based bitsets for external CFI checks. * Sets a module flag to enable __cfi_check generation during LTO. This mode does not yet support diagnostics. llvm-svn: 255694
2015-12-11docs: Document -fno-sanitize-trap= and -fsanitize-recover= flags for CFI.Peter Collingbourne
llvm-svn: 255393
2015-12-04[Docs] Move the list of CFI schemes down to CFI doc, and update it.Alexey Samsonov
Use proper headling levels in CFI doc. Before that, all sections were considered a subsection of "Introduction". Reviewers: pcc, kcc Subscribers: cfe-commits Differential Revision: http://reviews.llvm.org/D15237 llvm-svn: 254771
2015-09-10CFI: Introduce -fsanitize=cfi-icall flag.Peter Collingbourne
This flag causes the compiler to emit bit set entries for functions as well as runtime bitset checks at indirect call sites. Depends on the new function bitset mechanism. Differential Revision: http://reviews.llvm.org/D11857 llvm-svn: 247238
2015-07-15CodeGen: Improve CFI type blacklisting mechanism.Peter Collingbourne
We now use the sanitizer special case list to decide which types to blacklist. We also support a special blacklist entry for types with a uuid attribute, which are generally COM types whose virtual tables are defined externally. Differential Revision: http://reviews.llvm.org/D11096 llvm-svn: 242286
2015-06-19[CFI] Require -flto instead of implying it.Alexey Samsonov
Summary: This is unfortunate, but would let us land http://reviews.llvm.org/D10467, that makes ToolChains responsible for computing the set of sanitizers they support. Unfortunately, Darwin ToolChains doesn't know about actual OS they target until ToolChain::TranslateArgs() is called. In particular, it means we won't be able to construct SanitizerArgs for these ToolChains before that. This change removes SanitizerArgs::needsLTO() method, so that now ToolChain::IsUsingLTO(), which is called very early, doesn't need SanitizerArgs to implement this method. Docs and test cases are updated accordingly. See https://llvm.org/bugs/show_bug.cgi?id=23539, which describes why we start all these. Test Plan: regression test suite Reviewers: pcc Subscribers: cfe-commits Differential Revision: http://reviews.llvm.org/D10560 llvm-svn: 240170
2015-04-02Implement CFI type checks for non-virtual calls.Peter Collingbourne
This uses the same class metadata currently used for virtual call and cast checks. The new flag is -fsanitize=cfi-nvcall. For consistency, the -fsanitize=cfi-vptr flag has been renamed -fsanitize=cfi-vcall. Differential Revision: http://reviews.llvm.org/D8756 llvm-svn: 233874
2015-03-14Implement bad cast checks using control flow integrity information.Peter Collingbourne
This scheme checks that pointer and lvalue casts are made to an object of the correct dynamic type; that is, the dynamic type of the object must be a derived class of the pointee type of the cast. The checks are currently only introduced where the class being casted to is a polymorphic class. Differential Revision: http://reviews.llvm.org/D8312 llvm-svn: 232241
2015-02-20Implement Control Flow Integrity for virtual calls.Peter Collingbourne
This patch introduces the -fsanitize=cfi-vptr flag, which enables a control flow integrity scheme that checks that virtual calls take place using a vptr of the correct dynamic type. More details in the new docs/ControlFlowIntegrity.rst file. It also introduces the -fsanitize=cfi flag, which is currently a synonym for -fsanitize=cfi-vptr, but will eventually cover all CFI checks implemented in Clang. Differential Revision: http://reviews.llvm.org/D7424 llvm-svn: 230055