References, and existing work:

- [Original Zulip thread in t-compiler](https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/.60-Zbranch-protection.60.20stability)
- [... continued in project-exploit-mitigations](https://rust-lang.zulipchat.com/#narrow/stream/343119-project-exploit-mitigations/topic/CFI.20option.20stabilisation)
- [`branch-protection` tracking issue](https://github.com/rust-lang/rust/issues/93754)
- [`cf-protection` (CET) tracking issue](https://github.com/rust-lang/rust/issues/93754)
- [Tracking issue for sanitizer support](https://github.com/rust-lang/rust/issues/39699)
- [Tracking Issue for LLVM Control Flow Integrity (CFI) Support for Rust](https://github.com/rust-lang/rust/issues/89653)

# Summary

|Options like this... |Become... |
|-----------------------------------------|------------------------------------------------------|
|_Various target-specific CFI choices..._ |`-Cabi-variant=cfi` |
|`-Zbranch-protection=pac-ret,bti` |`-Zabi-variant=aarch64:branch-protection:pac-ret,bti` |
|`-Ccontrol-flow-guard=yes` |`-Cabi-variant=windows:control-flow-guard:on` |

# Objectives

Our long-term objectives are **to make CFI mitigations easy to enable in
Rust/Cargo, project-wide.**

However, the scope of _this_ proposal is simply **to define a command-line interface
for controlling CFI options**, as a step towards the overall objective.

In particular, whilst the command-line interface for stable and unstable options
is considered, no additional stabilisation is considered here today.

## Background and scope

Typically, CFI (control-flow integrity) mitigations are implemented as
target-specific ABI variants. Rust already has some support for enabling these
variants, for example as target-specific CodeGen options:

- [`-Zbranch-protection`][] (for AArch64),
- [`-Zcf-protection`][] (for x86),
- [`-Ccontrol-flow-guard`][] (for Windows).

_In addition, this proposal overlaps somewhat with [`-Zsanitizer`][]. See the [open questions (at the end)](#-Zsanitizer), for a discussion._

However, they aren't straightforward to use:

1. All but `-Ccontrol-flow-guard` are unstable.
2. The unstable (Cargo) `build-std` option is required to get a `std` built with
the same flags.
3. `cc-rs` does not forward these settings to the C compiler, so included C code
(including some examples in `std`) will not include mitigations.

A similar, but technically distinct problem occurs with the C library, which is
usually dynamically linked with Rust binaries. Since this is already an external
dependency, we might consider this out of Rust's scope, but that at least
requires documentation.

Note that, to be effective, most of these CFI techniques require that _all_ code
in a process is protected. Even unreachable binary code can be targeted by CFI
attacks if it is loaded into an executable memory region. Usually, this is a
security concern, but we also consider that correct deployment may be required
for the _correctness_ of some techniques.

We hope to find solutions to these problems, perhaps by stabilising `build-std`,
but such solutions are out of scope of this proposal.

One minor inconsistency with the existing options is the handling of errors:
`control-flow-guard` is ignored for targets other than Windows, whilst
`branch-protection` fails if the target is not AArch64. This proposal aims to
unify the behaviours here.

[`-Zbranch-protection`]: https://doc.rust-lang.org/unstable-book/compiler-flags/branch-protection.html
[`-Zcf-protection`]: https://doc.rust-lang.org/unstable-book/compiler-flags/cf-protection.html
[`-Ccontrol-flow-guard`]: https://doc.rust-lang.org/rustc/codegen-options/index.html#control-flow-guard
[`-Zsanitizer`]: https://doc.rust-lang.org/unstable-book/compiler-flags/sanitizer.html

## Use-cases and motivation

### Rust-C interoperability

C (or C++) projects might already deploy CFI mitigations, and this might even be
mandated by a system's security analysis team. If they introduce Rust code,
they will need a way to ensure that it implements the same standard of
mitigation.

This may also be required for some mixed-language LTO use-cases.

**Rust should provide options that map, in a simple and easy-to-audit fashion,
onto common C compiler options.**

In addition, if new options are added to future C compilers, we should be able
to support them in Rust too.

### Pure-Rust applications

A notable disadvantage of matching C compiler options is that they are
target-specific, which makes them difficult to use in a project that is
otherwise target-agnostic Rust.

**Rust should provide simple, target-agnostic Rust options that map, in a
target-specific manner, onto some ABI variant.**

The specific mitigations used will vary from one target to another, and for some
targets may not be possible at all. The behaviour should be "best-effort":
targets that don't implement the option can simply ignore it, perhaps with a
warning.

### Fine control where required

Fine control is required for Rust-C interoperability, but may also apply to
pure-Rust programs, providing very fine control over the mitigations used, at
expense of portability. For example, the `pac-ret` scheme for AArch64 can be
deployed with one of two keys ("A" or "B"). **Rust should allow this
flexibility**, even if it is not exposed by default.

This is quite unlike the general, best-effort approach. If fine control is
requested, it would be misleading for Rust to ignore it, so Rust should instead
refuse to build the project.

### Room for future growth

C compilers typically have to be concerned about compatibility, so that compiled
functions can be linked together without recompilation. Rust's approach of
statically linking (almost) everything somewhat frees it from this restriction,
and potentially allows it to deploy mitigations very quickly, at least when
using the Rust ABI.

In addition, we observe that whilst all mitigations listed here concern CFI,
that need not always be the case. For example, AArch64 Pointer Authentication
can also be used for data protection. Ideally, the option name should be chosen
with this in mind.

We propose no new ABI variants today, but the command-line interface proposal
should allow for such additions.

### Turning things off

Currently, none of these features are enabled by default. However, if that were
to change (or if a default was set earlier on the command line), it can be
useful to have a means to turn them off. This is possible today for
`cf-protection` and `control-flow-guard`, but not for `branch-protection`, which
is purely additive. It would be useful to make these consistent.

# The proposal

## `-Cabi-variant=...` / `-Zabi-variant=...`

1. This is principally a [CodeGen option][] so it makes sense under `-C` rather
than at the top level.
2. Keeping both `-C` and `-Z` forms provides a deployment path for new options
that avoids them being instantly stable after `abi-variant` itself is stable.
3. Grouping everything under one option makes similar options for different
targets easier to find, and makes it easier to keep the interface consistent.
4. The existing, stable `-Ccontrol-flow-guard` should remain, for
backwards-compatibility, but becomes an alias for `abi-variant` options.
5. The existing, unstable `-Zbranch-protection` and `-Zcf-protection` should
also remain for some transition period, but may be removed in the future.
6. The name `abi-variant` is not currently in use, so should not come with any
particular behaviour expectations.
7. The name is not specific to CFI.

[CodeGen option]: https://doc.rust-lang.org/rustc/codegen-options/index.html

The option's value is a comma-separated list of zero or more `<variant>`
names, preceded by zero or more `<group>:` selectors. However, behaviour
differs slightly if no `<group>` is provided.

### `<variant>`

Top-level variants (without any `<group>`) are high-level, best-effort
protections. Suggested flags include:

- `backward-edge-cfi`, which enables best-effort backward-edge CFI.
- This might enable `aarch64:branch-protection:pac-ret`,
`x86:cf-protection:return`, something else, or nothing at all.
- `forward-edge-cfi`, which enables best-effort forward-edge CFI.
- This might enable `aarch64:branch-protection:bti`,
`x86:cf-protection:branch`, something else, or nothing at all.
- `cfi` enables both of the above.
- `none` (the default) disables all top-level protections.

All of these top-level variants work on a best-effort basis. It is an error to
name a variant that doesn't exist, but if a known variant cannot be implemented
for the compiler target, it is simply ignored. In addition, Rust may change the
exact meanings of these flags, for example if new techniques are introduced in
future versions.

Top-level variants are treated as simple shortcuts for target-specific variants
_that the target platform supports_, and are intended to avoid target-specific
configuration in build infrastructure.

### `<group>:[<group>:]...[<variant>,]...`

`<group>`-specific variants are treated as precise, target-specific controls.
Typically, we expect the first `<group>` to specify the target (or group of
targets), and the next `<group>` to match the name of the de-facto C compiler
option (if there is one).

For example:

- `-Cabi-variant=aarch64:branch-protection:pac-ret,bti`
- `-Cabi-variant=x86:cf-protection:branch`
- `-Cabi-variant=x86:cf-protection:branch,return` (or equivalently, `x86:cf-protection:full`)
- `-Cabi-variant=windows:control-flow-guard:on`

Groups may be named loosely, but are chosen as a compromise between verbosity
and specificity. Notably, we don't expect to see full target triples here. For
example, "aarch64" would group features that only make sense on `aarch64*`
targets, but we don't require that _all_ `aarch64*` targets can actually
implement the included `<variants>`.

It is an _error_ to specify a variant under a named group unless that variant is
actually supported by the target.

### Combinations

It is valid to combine target-specific variants with a more general top-level
baseline, but we provide no forward-compatibility guarantees for this use-case.
For example, the following will work according to this proposal, but if `cfi` is
later updated to use something other than `pac-ret`, then `b-key` will be
invalid:

`-Cabi-variant=cfi -Cabi-variant=aarch64:branch-protection:b-key`

However, it may be useful to permit these combinations for use-cases where we
want a "good" baseline, but want fine control over some aspects:

`-Cabi-variant=forward-edge-cfi -Cabi-variant=aarch64:branch-protection:pac-ret,b-key`

**Is this behaviour reasonable? Should we instead forbid mixing these at all?**

### Evaluation

Evaluation should be intuitive, but the exact rules are described here to avoid
misunderstandings. The existing options have slightly different behaviours, so
different readers may have different intuitions.

Variants are evaluated in command-line order, then first to last in the
comma-separated list. Variants are typically additive, but that isn't required.
We expect `none` and `off` to have the effect of disabling the whole `<group>`
(but nothing outside it).

We don't check validity until the last `abi-variant` has been parsed. Note that
this differs from today's `branch-protection`, for example, which checks
validity as it goes (and therefore permits `pac-ret,leaf` but not
`leaf,pac-ret`).

`<group>` selections can only be specified once per `-Cabi-variant`, but in all
other respects, multiple `abi-variant` options are equivalent to a single option
with multiple `<variant>`s. For example, the following are all equivalent
(assuming that `none` is the default):

- `-Cabi-variant=aarch64:branch-protection:pac-ret,bti`
- `-Cabi-variant=aarch64:branch-protection:pac-ret -Cabi-variant=aarch64:branch-protection:bti`
- `-Cabi-variant=aarch64:branch-protection:b-key -Cabi-variant=aarch64:branch-protection:none,bti -Cabi-variant=aarch64:branch-protection:pac-ret`

## `-Zabi-variant`

The unstable form of the option should remain permanently, and behave
identically to the stable form. The only difference is that the unstable
`abi-variant` can accept unstable `<variant>`s. This allows us to extend the
interface gracefully, without breaking stability rules.

Notably, it is possible to combine both forms. The following are all equivalent
(with a nightly compiler):

- `-Cabi-variant=forward-edge-cfi -Zabi-variant=backward-edge-cfi`
- `-Cabi-variant=cfi`
- `-Zabi-variant=cfi`

## Initially-supported variants

|`-Zabi-variant=...` |Meaning |
|---------------------------------|---------------------------------------------------|
|`aarch64:branch-protection:...` |`-Zbranch-protection=...` |
|`x86:cf-protection:...` |`-Zcf-protection=...` |
|`windows:control-flow-guard:...` |`-Ccontrol-flow-guard=...` |
|`forward-edge-cfi` |_Varies with target._ |
|`backward-edge-cfi` |_Varies with target._ |
|`cfi` |`-Zabi-variant=backward-edge-cfi,forward-edge-cfi` |

Once `abi-variant` itself is stabilised:

|`-Cabi-variant=...` |Meaning |
|---------------------------------|---------------------------------------------------|
|`aarch64:branch-protection:...` |_Rejected until `branch-protection` is stable._ |
|`x86:cf-protection:...` |_Rejected until `cf-protection` is stable._ |
|`windows:control-flow-guard:...` |`-Ccontrol-flow-guard=...` |
|`forward-edge-cfi` |_Varies with target._ |
|`backward-edge-cfi` |_Varies with target._ |
|`cfi` |`-Cabi-variant=backward-edge-cfi,forward-edge-cfi` |

# Open questions

## `-Zsanitizer`

There is considerable overlap between this proposed `{-Z,-C}abi-variant` and the
existing (unstable) `-Zsanitizer`, because many of the available sanitizers
could be viewed as ABI variants.

**Question: should this proposal be merged with `-Zsanitizer`?**

`{-Z,-C}abi-variant` has three notable properties that `-Zsanitizer` lacks:

1. Target-specific variants are distinguished, at least partially.
2. Best-effort options can be described.
3. Individual variants can be stabilised without affecting other unstable
variants (though the same technique could be applied to `{-Z,-C}sanitizer`).

It is clearly undesirable to maintain `abi-variant` mappings for every
`sanitizer` option. Would it instead be acceptable to _replace_ `sanitizer` with
`abi-variant`? Alternatively, if the `abi-variant` behaviours described here are
deemed useful, should we attempt to fit them under the existing `sanitizer`
option?

Also note that the naming might require further attention. `abi-variant`
currently covers technologies that are designed to be used in release builds, in
production. They will have a performance and code-size overhead, but should be
"light". Conversely, the term `sanitizer` suggests more comprehensive debug and
test tools, though many of its options are clearly designed for deployment too.

# Answers to common or expected questions

## Can't this be a target feature?

The ABI variant describes what the compiler should _do_, whilst the target
features describe the set of tools it has available to do it. For example:

- Variants might be backwards-compatible, operating in a reduced form (or as
no-ops) if some target features are unavailable. For example, `pac-ret`
generates instructions that were no-ops before Armv8.3 Pointer Authentication
was introduced.
- Conversely, better code generation might be possible if the compiler _knows_
that a given target feature is available. For example, if `paca` is enabled at
compile-time, Rust might implement `pac-ret` using instructions that weren't
interpreted as no-ops prior to Armv8.3 Pointer Authentication.

We also consider the possibility that an ABI variant might _require_ a target,
or target feature. Specifying such a variant should cause a compile-time error,
as noted earlier. For example, [`-Zsanitizer=shadow-call-stack`][] is only
available on `aarch64-linux-android`.

[`-Zsanitizer=shadow-call-stack`]: https://doc.rust-lang.org/unstable-book/compiler-flags/sanitizer.html#shadowcallstack