Documentation: Add Box ID

DOCUMENTATION.md

@@ -4,6 +4,7 @@ Here you can find detailed documentation for:
 
 1. [Configuration macros](#configuration-macros), to configure a secure box and protect data and peripherals.
 1. [Secure function calls](#secure-function-call), to execute code in the context of a secure box.
+1. [Box Identity](#box-identity), to retrieve a box-specific ID or the namespace of the current or calling box.
 1. [Low level APIs](#low-level-apis), to access uVisor functions that are not available to unprivileged code (interrupts, restricted system registers).
 1. [Type definitions](#type-definitions).
 1. [Error codes](#error-codes).
@@ -67,6 +68,7 @@ static const UvBoxAclItem g_box_acl[] = {
 };
 
 /* Configure the secure box compartment. */
+UVISOR_BOX_NAMESPACE("com.example.my-box-name");
 UVISOR_BOX_CONFIG(my_box_name, g_box_acl, BOX_STACK_SIZE, BoxContext);
 ```
 
@@ -166,6 +168,45 @@ UVISOR_SET_MODE_ACL(UVISOR_ENABLED, g_background_acl);
 
 2. This macro must be used only once in the top level yotta executable.
 
+---
+
+```C
+UVISOR_BOX_NAMESPACE(static const char const namespace[])
+```
+
+<table>
+  <tr>
+    <td>Description</td>
+    <td colspan="2"><p>Specify the namespace for a box.</p>
+
+      <p>The namespace of the box must be a null-terminated string no longer than <code>MAX_BOX_NAMESPACE_LENGTH</code> (including the terminating null). The namespace must also be stored in public flash. uVisor will verify that the namespace is null-terminated and stored in public flash at boot-time, and will halt if the namespace fails this verification.</p>
+
+      <p>For now, use a reverse domain name for the box namespace. If you don't have a reverse domain name, use a GUID string identifier. We currently don't verify that the namespace is globally unique, but we will perform this validation in the future.</p>
+
+      <p>Use of this configuration macro before <code>UVISOR_BOX_CONFIG</code> is required. If you do not wish to give your box a namespace, specify <code>NULL</code> as the namespace to create an anonymous box.</p>
+  </tr>
+  <tr>
+    <td>Type</td>
+    <td colspan="2">C/C++ pre-processor macro (pseudo-function)</td>
+  </tr>
+  <tr>
+    <td rowspan="1">Parameters</td>
+    <td><code>namespace</code></td>
+    <td>The namespace of the box</td>
+  </tr>
+</table>
+
+Example:
+```C
+#include "uvisor-lib/uvisor-lib.h"
+
+/* Configure the secure box. */
+UVISOR_BOX_NAMESPACE("com.example.my-box-name");
+UVISOR_BOX_CONFIG(my_box_name, UVISOR_BOX_STACK_SIZE);
+```
+
+---
+
 ## Secure function call
 
 ```C
@@ -218,6 +259,82 @@ uint32_t secure_sum(uint32_t op1, uint32_t op2)
 }
 ```
 
+## Box Identity
+
+A box identity identifies a security domain uniquely and globally.
+
+The box identity API can be used to determine the source box of an inbound secure gateway call. This can be useful for implementing complex authorization logic between mutually distrustful security domains.
+
+uVisor provides the ability to retrieve the box ID of the current box (`uvisor_box_id_self`), or of the box that most recently called the current box through a secure gateway (`uvisor_box_id_caller`).
+
+The box ID number is not constant and can change between reboots. But, the box ID number can be used as a token to retrieve a constant string identifier, known as the box namespace.
+
+A box namespace is a static, box-specific string, that can help identify which box has which ID at run-time. In the future, the box namespace will be guaranteed to be globally unique.
+
+A full example using this API is available at [example-uvisor-box-id](https://github.com/ARMmbed/example-uvisor-box-id).
+
+```C
+int uvisor_box_id_self(void)
+```
+
+<table>
+  <tr>
+    <td>Description</td>
+    <td colspan="2">Get the ID of the current box</td>
+  </tr>
+  <tr>
+    <td>Return value</td>
+    <td colspan="2">The ID of the current box</td>
+  </tr>
+</table>
+
+---
+
+```C
+int uvisor_box_id_caller(void)
+```
+
+<table>
+  <tr>
+    <td>Description</td>
+    <td colspan="2">Get the ID of the box that is calling the current box through the most recent secure gateway</td>
+  </tr>
+  <tr>
+    <td>Return value</td>
+    <td colspan="2">The ID of the caller box, or -1 if there is no secure gateway calling box</td>
+  </tr>
+</table>
+
+---
+
+```C
+int uvisor_box_namespace(int box_id, char *box_namespace, size_t length)
+```
+
+<table>
+  <tr>
+    <td>Description</td>
+    <td colspan="2">Copy the namespace of the specified box to the provided buffer.</td>
+  </tr>
+  <tr>
+    <td>Return value</td>
+    <td colspan="2">Return how many bytes were copied into <code>box_namespace</code>. Return <code>UVISOR_ERROR_INVALID_BOX_ID</code> if the provided box ID is invalid. Return <code>UVISOR_ERROR_BUFFER_TOO_SMALL</code> if the provided <code>box_namespace</code> is too small to hold <code>MAX_BOX_NAMESPACE_LENGTH</code> bytes. Return <code>UVISOR_ERROR_BOX_NAMESPACE_ANONYMOUS</code> if the box is anonymous.</td>
+  </tr>
+  <tr>
+    <td rowspan="3">Parameters</td>
+    <td><code>int box_id</code></td>
+    <td>The ID of the box you want to retrieve the namespace of</td>
+  </tr>
+  <tr>
+    <td><code>char *box_namespace</code></td>
+    <td>The buffer where the box namespace will be copied to</td>
+  </tr>
+  <tr>
+    <td><code>size_t length</code></td>
+    <td>The length in bytes of the provided <code>box_namespace</code> buffer</td>
+  </tr>
+</table>
+
 ## Low-level APIs
 
 Currently the following low level operations are permitted: