New document for gcc and clang annotation recommendations

Add a document with recommendation for clang and GCC attributes.  This
is a first draft and needs more information to be added to better
describe the implications of each attribute.

The document is currently also missing the standard C attribute names
for many of these attributes, which could potentially make them even
more portable.

Signed-off-by: Siddhesh Poyarekar <[email protected]>

docs/Compiler-Hardening-Guides/Compiler-Annotations-for-C-and-C++.md

@@ -0,0 +1,42 @@
+# Compiler Annotations for C and C++
+
+Compile time security analysis and runtime mitigation implemented in compilers both depend on the compiler being able to see the flow of data between different points in a program, across functions and modules. This is quite a challenge in C and C++ because both languages allow passing around opaque references, thus losing information about objects.  To work around this problem, both GCC and Clang implement attributes to annotate source code, especially functions and data structures, to allow them to do better analysis of source code.  These annotations are not only beneficial for security, but they also help the compilers make better optimization decisions, often resulting in better code.
+
+## Clang and GCC Attributes at a glance
+
+Both GCC and Clang recognize the `__attribute__` keyword to annotate source code.  Both compilers also provide a `__has_attribute()` macro function that returns 1 if the attribute name passed to it is supported and 0 otherwise.  For example `__has_attribute(malloc)` would return 1 in the latest GCC and Clang.  The full syntax description for the `__attribute__` keyword is available in the GCC documentation[^1].  Since all of the attributes recommended in this document are function attributes, here's a quick primer on how they are used.
+
+When declaring functions, attributes may be added to the function at the end of the declaration, like so:
+
+```
+extern void *custom_allocator (size_t sz) __attribute__ ((malloc)) __attribute__ ((alloc_size (1)));
+```
+
+At function definition, function attributes come right before the function name:
+
+```
+void * __attribute__ ((malloc)) __attribute__ ((alloc_size (1))) custom_allocator (size_t sz);
+```
+
+Some function attributes can accept parameters that have specific meanings.  Parameters can be numbers that indicate the position of the argument to the function; 1 indicates the first argument, 2 the second and so on.  Parameters can also be keywords or names of identifiers that have been declared earlier in the program.
+
+Table 1: Recommended attributes
+
+| Compiler Flag                                     |       Supported by    | Type     | Description                                                                         |
+|:------------------------------------------------- |:---------------------:|:--------:|:----------------------------------------------------------------------------------- |
+| `malloc`                                          | GCC<br/>Clang 13 | Function | Allocator that returns a non-aliased (possibly NULL) pointer.                   |
+| `malloc (dealloc)`                                | GCC 11 | Function | Same as above but also associate `dealloc` as the deallocator for this function |
+| `alloc_size(pos)`<br/>`alloc_size(pos-1, pos-2)`  | GCC <br/>Clang | Function | Size of the object that the returned pointer points to is at argument `pos` of the function or product of arguments at `pos-1` and `pos-2`. |
+| `access(mode, ref-pos)`<br/>`access(mode, ref-pos, size-pos)`  | GCC 10 | Function | Indicate how the function uses argument at `ref-pos`.  `mode` could be `read_only`, `read_write`, `write_only` or `none`.  `size-pos`, if mentioned, is the argument indicating the size of object at `ref-pos`. |
+| `fd_arg(N)`                                          | GCC 13 | Function | Argument N is an open file descriptor.                   |
+| `fd_arg_read(N)`                                          | GCC 13 | Function | Argument N is an open file descriptor that can be read from.                   |
+| `fd_arg_write(N)`                                          | GCC 13 | Function | Argument N is an open file descriptor that can be written to.                   |
+| `noreturn`                                          | GCC<br/>Clang | Function | The function does not return.                   |
+| `tainted_args`                                          | GCC 12<br/>Clang TBD | Function or function pointer | Function needs sanitization of its arguments. Used by -fanalyzer=taint                  |
+
+## Performance considerations
+
+Attributes influence not only diagnostics generated by the compiler but also the resultant code. As a result, annotating code with attributes will have an impact on performance, although the impact may go either way.  The annotation may allow compilers to add more traps for additional security and be conservative about some optimizations, thus impacting performance of output code. At the same time however, it may allow compilers to make some aggressive optimization decisions, resulting in generation of smaller and faster running code and often, better code layout.
+
+[^1]: Attribute Syntax
+<https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html>