From 8d5c80e2c6b62170acafce3b2fa65cef8def2cc1 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Tue, 15 Mar 2016 15:42:36 +0000 Subject: [PATCH 1/2] Documentation: Auto-number the sections --- DOCUMENTATION.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index d879fff..73ce706 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -3,10 +3,10 @@ Here you can find detailed documentation for: 1. [Configuration macros](#configuration-macros), to configure a secure box and protect data and peripherals. -2. [Secure function calls](#secure-function-call), to execute code in the context of a secure box. -3. [Low level APIs](#low-level-apis), to access uVisor functions that are not available to unprivileged code (interrupts, restricted system registers). -4. [Type definitions](#type-definitions). -5. [Error codes](#error-codes). +1. [Secure function calls](#secure-function-call), to execute code in the context of a secure 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). ## Configuration macros From cfc7a2dc93b9ba2f2144e43ac3bc8e2bdb87e8cb Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Tue, 15 Mar 2016 18:04:46 +0000 Subject: [PATCH 2/2] Documentation: Add Box ID --- DOCUMENTATION.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 73ce706..715cc80 100644 --- a/DOCUMENTATION.md +++ b/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[]) +``` + + + + + + + + + + + + + + +
Description

Specify the namespace for a box.

+ +

The namespace of the box must be a null-terminated string no longer than MAX_BOX_NAMESPACE_LENGTH (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.

+ +

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.

+ +

Use of this configuration macro before UVISOR_BOX_CONFIG is required. If you do not wish to give your box a namespace, specify NULL as the namespace to create an anonymous box.

+
TypeC/C++ pre-processor macro (pseudo-function)
ParametersnamespaceThe namespace of the box
+ +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) +``` + + + + + + + + + + +
DescriptionGet the ID of the current box
Return valueThe ID of the current box
+ +--- + +```C +int uvisor_box_id_caller(void) +``` + + + + + + + + + + +
DescriptionGet the ID of the box that is calling the current box through the most recent secure gateway
Return valueThe ID of the caller box, or -1 if there is no secure gateway calling box
+ +--- + +```C +int uvisor_box_namespace(int box_id, char *box_namespace, size_t length) +``` + + + + + + + + + + + + + + + + + + + + + + + +
DescriptionCopy the namespace of the specified box to the provided buffer.
Return valueReturn how many bytes were copied into box_namespace. Return UVISOR_ERROR_INVALID_BOX_ID if the provided box ID is invalid. Return UVISOR_ERROR_BUFFER_TOO_SMALL if the provided box_namespace is too small to hold MAX_BOX_NAMESPACE_LENGTH bytes. Return UVISOR_ERROR_BOX_NAMESPACE_ANONYMOUS if the box is anonymous.
Parametersint box_idThe ID of the box you want to retrieve the namespace of
char *box_namespaceThe buffer where the box namespace will be copied to
size_t lengthThe length in bytes of the provided box_namespace buffer
+ ## Low-level APIs Currently the following low level operations are permitted: