[llvm] [BOLT] Rework user-facing documentation of BOLT gadget scanner (PR #176446)

[Kristof Beyls via llvm-commits]

================
@@ -61,126 +64,641 @@ The security scanners implemented in `llvm-bolt-binary-analysis` aim to enable
 the testing of security hardening in arbitrary programs and not just specific
 examples.
 
+### Pointer Authentication
+
+[Pointer Authentication](https://clang.llvm.org/docs/PointerAuthentication.html)
+is intended to make it harder for an attacker to replace pointers at run time.
+This is achieved by making it possible for the compiler or the programmer to
+produce a *signed* pointer from a raw one, and then to probabilistically
+*authenticate the signature* at another site in the program.
+On AArch64 this is achieved by injecting a cryptographic hash, called a
+["Pointer Authentication Code" (PAC)](https://llsoftsec.github.io/llsoftsecbook/#sec:pointer-authentication),
+to the upper bits of the pointer.
+While this approach can be applied to any pointers in the program, the most
+frequent use case, at least in C and C++, is protecting the code pointers.
+The language rules for such pointers are more restrictive, thus allowing the
+compiler to implement various hardenings transparently to the programmer.
+
+Probably the most simple variant of hardening based on Pointer Authentication is
+[`pac-ret`](https://llsoftsec.github.io/llsoftsecbook/#sec:pac-ret), a security
+hardening scheme implemented in compilers such as GCC and Clang, using the
+command line option `-mbranch-protection=pac-ret`. This option is enabled by
+default on most widely used Linux distributions. The hardening scheme mitigates
+[Return-Oriented Programming (ROP)](https://llsoftsec.github.io/llsoftsecbook/#return-oriented-programming)
+attacks by making sure that return addresses are only ever stored to memory
+in a signed form. This makes it substantially harder for attackers to divert
+control flow by overwriting a return address with a different value.
 
-#### pac-ret analysis
+The approach to validation of Pointer Authentication hardening implemented in
+`llvm-bolt-binary-analysis` is tracking register safety using dataflow analysis.
+At each program point it is computed whether the particular register can be
+controlled and whether it can be inspected by an attacker under
+[Pointer Authentication threat model](https://clang.llvm.org/docs/PointerAuthentication.html#theory-of-operation).
+Then, for a number of sensitive instruction kinds (such as function calls and
+pointer signing instructions), the properties of input or output operands are
+inspected to check if the particular instruction is emitted in a safe manner.
----------------
kbeyls wrote:

That example looks great, thanks for adding it!

https://github.com/llvm/llvm-project/pull/176446