docs: Add the list of banned/use with caution APIs

Credit to sam.ellis@arm.com for the input to create the list.

Change-Id: Id70a8eddc5f2490811bebb278482c61950f10cce
Signed-off-by: Soby Mathew <soby.mathew@arm.com>

diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst
index d524d733179b96126774ea341e5fcc3dce77bc35..093d66be3e45fe73cf57e209401be3e99513510c 100644 (file)
--- a/docs/process/coding-guidelines.rst
+++ b/docs/process/coding-guidelines.rst
@@ -263,6 +263,41 @@ a warning for this.
 
 Existing typedefs will be retained for compatibility.
 
+Libc functions that are banned or to be used with caution
+---------------------------------------------------------
+
+Below is a list of functions that present security risks and either must not be
+used (Banned) or are discouraged from use and must be used with care (Caution).
+
++------------------------+-----------+--------------------------------------+
+|    libc function       | Status    | Comments                             |
++========================+===========+======================================+
+| ``strcpy, wcscpy``     | Banned    | use strlcpy instead                  |
+| ``strncpy``            |           |                                      |
++------------------------+-----------+--------------------------------------+
+| ``strcat, wcscat``     | Banned    | use strlcat instead                  |
+| ``strncat``            |           |                                      |
++----------------------- +-----------+--------------------------------------+
+| ``sprintf, vsprintf``  | Banned    | use snprintf, vsnprintf              |
+|                        |           | instead                              |
++---------------------- -+-----------+--------------------------------------+
+| ``snprintf``           | Caution   | ensure result fits in buffer         |
+|                        |           | i.e : snprintf(buf,size...) < size   |
++------------------------+-----------+--------------------------------------+
+| ``vsnprintf``          | Caution   | inspect va_list match types          |
+|                        |           | specified in format string           |
++------------------------+-----------+--------------------------------------+
+| ``strtok``             | Banned    | use strtok_r or strsep instead       |
++------------------------+-----------+--------------------------------------+
+| ``strtok_r, strsep``   | Caution   | inspect for terminated input buffer  |
++------------------------+-----------+--------------------------------------+
+| ``ato*``               | Banned    | use equivalent strto* functions      |
++------------------------+-----------+--------------------------------------+
+| ``*toa``               | Banned    | Use snprintf instead                 |
++------------------------+-----------+--------------------------------------+
+
+The `libc` component in the codebase will not add support for the banned APIs.
+
 Error handling and robustness
 -----------------------------