|
|
# The SecBus virtual prototype
|
|
|
|
|
|
SecBus is available in the form of a simulator of a ARM or Mips based system equipped with our technology. It runs an example application on top of a tiny Operating System (OS). The example application is a kind of interactive shell that allows to play with the security policies applied to memory pages, launch attacks and see how SecBus prevents them. In the following we will guide you step by step to download, install and compile the virtual prototype of a complete SecBus equipped platform. Then, we will download, install and compile the SecBus software components:
|
|
|
|
|
|
* The drivers of the Hardware Security Module (HSM). They reside in the internal ROM and are used by the boot loader and the Software Security Manager (SSM).
|
|
|
* The boot loader, the first piece of software than runs after reset or power up. Its two main roles are to initialize the HSM and to load, check, install and jump into the next software layer (the MutekH kernel in our example). For security reasons, this tiny piece of software resides in an internal ROM of the SoC and runs only in an internal RAM.
|
|
|
* MutekH, the Operating System (OS) used in this example. Please visit the MutekH web site (https://www.mutekh.org/) to learn more about this nice, tiny, highly configurable OS.
|
|
|
* The Software Security Manager (SSM). The SSM is the software component that manages the SecBus security when requested by the OS.
|
|
|
* The example application, a tiny interactive shell that can be used to manage the platform's security, check that it is working and even fire a virtual attacker: a supposedly compromised Direct Memory Access (DMA) capable hardware peripheral.
|
|
|
|
|
|
Finally, we will run the example application (on top of the HSM drivers, the SSM and the OS) on the virtual prototypes and play with the SecBus main security features.
|
|
|
|
|
|
The provided virtual prototype is a fast, bit accurate, cycle approximate simulator of a complete SecBus equipped platform. It runs on a regular GNU/Linux box. Of course it is not as fast as the real hardware but it is sufficiently fast to boot our tiny operating system and run the example application. It is also much easier to install and run. If you intend to test what SecBus is, installing and running the virtual prototype is the next step after reading the introduction. The virtual prototype embeds a simulation model of a General Purpose Processor (GPP), of the Hardware Security Module (HSM), of a set of peripherals and of external memories. Two different CPU architectures are currently supported: ARM and Mips. The virtual prototype has been tested on 64 bits Fedora, Debian, ArchLinux and Ubuntu operating systems. It should work unmodified or with minor changes on most UNIX-like systems. There are no plans to support or test it on Apple or Microsoft OSes. Please feel free to port it but do not expect any help on this.
|
|
|
|
|
|
Please follow the instructions below to install the virtual prototype and to run the provided example software application on it. The virtual prototype relies on several free / open source software packages. If needed, please refer to their own web sites and installation instructions to download and install them.
|
|
|
|
|
|
## SystemC or SystemCASS
|
|
|
|
|
|
The virtual prototype is written in SystemC, a hardware description language based on C++. The coding style is 100% compatible with the SystemCASS implementation of SystemC. If you want to benefit from the 5 to 10x acceleration of SystemCASS, you can.
|
|
|
|
|
|
### SystemC
|
|
|
|
|
|
If you do not have SystemC installed already, please download the SystemC distribution from the Accellera web site (http://www.accellera.org/home/), install it and define the `SYSTEMC` environment variable:
|
|
|
|
|
|
```bash
|
|
|
export SYSTEMC=<path-to-systemc-installation-directory>
|
|
|
```
|
|
|
|
|
|
### SystemCASS
|
|
|
|
|
|
If you prefer the SystemCASS way, please download it from its Subversion repository and install it:
|
|
|
|
|
|
```bash
|
|
|
export SYSTEMC=<path-to-systemcass-installation-directory>
|
|
|
svn co https://www.soclib.fr/svn/systemcass /tmp/systemcass
|
|
|
cd /tmp/systemcass/source
|
|
|
./bootstrap
|
|
|
./configure --prefix=$SYSTEMC
|
|
|
make
|
|
|
make install
|
|
|
cd $SYSTEMC
|
|
|
ln -s lib-linux lib-linux64
|
|
|
```
|
|
|
|
|
|
## The tool chain
|
|
|
|
|
|
In order to compile the software components that you will run on the virtual prototype you need cross-compilers, linkers, debuggers, software lbraries... All the needed pre-compiled binaries are available from the MutekH web site (in https://www.mutekh.org/www/tools/precompiled/). The same binaries for the ARM and Mips architectures are also available in the [downloads section]. They are designed to be installed in `/opt/mutekh`. Of course, if you know how to do so, and if you prefer the hard way, you can visit the GNU web sites, download the sources and compile them. Install the tool chain and make sure to add the binaries to your `PATH`:
|
|
|
|
|
|
```bash
|
|
|
tar zxf <some-path>/mutekh-arm-toolchain-<version>-i386-linux.tar.gz -C /
|
|
|
tar zxf <some-path>/mutekh-mipsel-toolchain-<version>-i386-linux.tar.gz -C /
|
|
|
export PATH=$PATH:/opt/mutekh/bin
|
|
|
```
|
|
|
|
|
|
## The SecBus virtual prototype and example software stack
|
|
|
|
|
|
Once the different pre-requisites are installed, it is time to install the SecBus virtual prototype and software stack. First download the provided archive (see the [downloads section]). In the following we assume that the archive is unpacked and that the SECBUS environment variable points to it:
|
|
|
|
|
|
```bash
|
|
|
tar zxf secbus.XXXXXXXXXX.tgz
|
|
|
cd secbus
|
|
|
export SECBUS=`pwd`
|
|
|
```
|
|
|
|
|
|
The unpacked archive contains several sub-directories:
|
|
|
|
|
|
* `mutekh/`: The MutekH OS
|
|
|
* `secbus/`: The SecBus virtual prototypes and software components
|
|
|
* `secbus/bootloader/`: The boot loader
|
|
|
* `secbus/drivers/`: The HSM software drivers
|
|
|
* `secbus/mutekh-add-ons/`: The SecBus add-ons for the MutekH OS
|
|
|
* `secbus/mutekh-add-ons/libssm/`: The SSM
|
|
|
* `secbus/mutekh-add-ons/demo/`: The example application
|
|
|
* `secbus/soclib-add-ons/`: The SecBus add-ons for the SoCLib library
|
|
|
* `secbus/soclib-add-ons/lib/`: Utilities
|
|
|
* `secbus/soclib-add-ons/module/`: SystemC model of the HSM
|
|
|
* `secbus/soclib-add-ons/platform/caba-secbus-arm-demo/`: The ARM-based virtual prototype
|
|
|
* `secbus/soclib-add-ons/platform/caba-secbus-mipsel32-demo/`: The Mips-based virtual prototype
|
|
|
* `secbus/tools/`: Utilities
|
|
|
* `soclib/`: The SoCLib library
|
|
|
|
|
|
## Compiling the virtual prototype, the software stack and running the simulation
|
|
|
|
|
|
We will first compile the virtual prototype, then the various software components (HSM drivers, first stage boot loader, SSM, MutekH OS and example application) and finally launch the simulation. In the following instructions please replace `<arm|mips>` by the architecture of your choice (`arm` or `mips`). Important note: a virtual prototype compiled and linked with the official SystemC library cannot be run with SystemCASS and conversely. If you want to switch from one to the other, first clean the virtual prototype (`make -C $SECBUS vp-<arm|mips>-clean`) and recompile it.
|
|
|
|
|
|
1. Compile the virtual prototype:
|
|
|
|
|
|
```bash
|
|
|
make -C $SECBUS vp-<arm|mips>
|
|
|
```
|
|
|
1. Compile the software stack:
|
|
|
|
|
|
```bash
|
|
|
make -C $SECBUS sw-<arm|mips>
|
|
|
```
|
|
|
1. Launch the simulation:
|
|
|
|
|
|
```bash
|
|
|
make -C $SECBUS sim-<arm|mips>
|
|
|
```
|
|
|
|
|
|
Debug messages will be printed in the terminal from which you launched the simulation. A pseudo-tty window will also pop up and other debug messages will also be printed in it.
|
|
|
|
|
|
The debug messages printed in the terminal are issued by the hardware models of the virtual prototype when they are requested. They first indicate that the virtual prototype is assembled. The last messages are debug messages printed by the HSM and giving information about the memory layout and the SecBus settings for memory protection:
|
|
|
|
|
|
![Debug messages](virtual-prototype/terminal.jpg)
|
|
|
|
|
|
The various software components print their own debug messages in the pseudo-tty. They show that the boot loader started its execution, initialized the HSM, loaded, checked and installed the MutekH kernel and jumped into it. The MutekH kernel, in turn, booted, discovered the hardware peripherals (including the SecBus HSM), attached them their respective software drivers, and jumped into the example application:
|
|
|
|
|
|
![MutekH boot](virtual-prototype/tty.jpg)
|
|
|
|
|
|
The `[demo]` prompt in the pseudo-tty indicates that the tiny example interactive shell is ready. Type `list` to get the list of available commands:
|
|
|
|
|
|
![Available commands](virtual-prototype/list.jpg)
|
|
|
|
|
|
Type `help <command>` to get some help about them:
|
|
|
|
|
|
![Help](virtual-prototype/help_protect.jpg)
|
|
|
|
|
|
Play around. To stop the simulation simply type `CTRL-C` in the terminal from which you launched the simulation.
|
|
|
|
|
|
## Playing with the example software application and testing the security
|
|
|
|
|
|
The provided example application is an interactive shell-like application, built on top of the MutekH OS. It offers a small set of basic commands to define security policies and assign them to memory pages, to read - write the external memory and to drive an external DMA engine (our attacker) in order to see SecBus in action.
|
|
|
|
|
|
The memory layout of the simulated system is as follows:
|
|
|
|
|
|
* `0x80000000 - 0x83ffffff`: the protected memory region (64 MB)
|
|
|
* `0x80000000`: kernel, followed by the pages of MAC sets and MAC trees needed for its integrity
|
|
|
* `0x80e04000`: stack
|
|
|
* `0x80e04000 - 0x80efffff`: heap
|
|
|
* `0x81000000`: pages of MAC sets and MAC trees for the user land (allocated by the SSM)
|
|
|
* `0x80f00000 - 0x80ff0000`: the sandbox memory area in which experiments can be done
|
|
|
* `0x91000000`: Master Block (256 KBytes)
|
|
|
* `0x91000000 - 0x9101ffff`: PSPEs (16384 = 128 kB)
|
|
|
* `0x91020000 - 0x9102ffff`: SP (1024 = 64 kB)
|
|
|
* `0x91030000 - 0x9103ffff`: Master MAC Tree (64 kB)
|
|
|
|
|
|
### The mini-shell commands
|
|
|
|
|
|
* `list`: Lists the available commands.
|
|
|
* `help COMMAND`: Prints a short help about the `COMMAND` command.
|
|
|
* `quit`: Quits the mini-shell application but does not stop the simulation of the virtual prototype. Unless there is a very good reason to do so, `shutdown` should probably be preferred. To stop the simulation after a `quit`, simply type `<CTRL>-C` in the console from which the simulation has been launched.
|
|
|
* `shutdown`: Quits the mini-shell application and stops the simulation of the virtual prototype.
|
|
|
* `protect ADDR SIZE INTEGRITY CONFIDENTIALITY`: Defines the security policy to apply to the memory area of size `SIZE` that starts at address `ADDR`. `INTEGRITY` is 0: none, 1: MAC set (for read-only pages) or 2: MAC tree (for read-write pages). `CONFIDENTIALITY` is 0: none, 1: counter mode (for read-only pages) or 2: cipher-block chaining (for read-write pages). Examples :
|
|
|
* `protect 0x80f00000 0x4000 2 2`: protects a 16kB area starting at address 0x80f00000 with MAC tree for integrity and cipher-block chaining for confidentiality.
|
|
|
* `protect 0x80f00000 0x1000 0 2`: protects the same region for confidentiality only with cipher-block chaining.
|
|
|
* `protect 0x80f00000 0x1000 1 1`: protects the same region with MAC set for integrity and counter mode for confidentiality.
|
|
|
* `read ADDR [SIZE]`: Reads `SIZE` bytes (default 1) starting at address `ADDR` and prints them. Example:
|
|
|
* `read 0x80f00000 0x100`: prints the 256 first bytes at 0x80f00000.
|
|
|
* `write ADDR CHAR [SIZE]`: Writes `SIZE` times (default 1) byte `CHAR` starting at address `ADDR`.Example:
|
|
|
* `write 0x80f00000 0x65 0x1000`: populates a complete 4kB memory page with byte 0x65, starting at address 0x80f00000.
|
|
|
* `writegroup ADDR CHAR [SIZE]`: Same as `write` but uses the atomic write operation of the HSM instead of the regular CPU load / store. Used to initialize read-only pages (in fact write-once-read-many). Initializing such pages with regular CPU load / store would lead to a security flaw because the write '''once''' would not hold.
|
|
|
* `dma_attack S_ADDR D_ADDR SIZE`: Programs the DMA engine (which is located between the HSM and the external memory) to perform a memory transfer of `SIZE` bytes from address `S_ADDR` to address `D_ADDR`. Can be used to test the security. Example:
|
|
|
* `dma_attack 0x80f00000 0x80f01000 0x1000`: Transfers 4kB from 0x80f00000 to 0x80f01000. If the source or destination pages are protected something interesting should happen.
|
|
|
|
|
|
### Example of use
|
|
|
|
|
|
In this little example we protect a 4kB region in integrity with MAC trees and in confidentiality with CBC. We populate it with some stuffing byte from the CPU (legal), read back from CPU, modify from CPU (legal). Then we use the attacker DMA to modify the content. On the next read by the CPU, the HSM immediately detects the integrity violation and raises an interrupt (that stops the simulation in the current version).
|
|
|
|
|
|
1. Read / write for testing:
|
|
|
|
|
|
```
|
|
|
read 0x80f10000 0x20
|
|
|
write 0x80f10000 0x9f 0x20
|
|
|
read 0x80f10000 0x20
|
|
|
```
|
|
|
|
|
|
1. Protect integrity and confidentiality
|
|
|
|
|
|
```
|
|
|
protect 0x80f10000 0x1000 2 2
|
|
|
```
|
|
|
|
|
|
1. Read / write data (encrypted / decrypted on-the-fly)
|
|
|
|
|
|
```
|
|
|
read 0x80f10000 0x20
|
|
|
write 0x80f10000 0x9f 0x20
|
|
|
read 0x80f10000 0x20
|
|
|
```
|
|
|
|
|
|
1. Move data with malicious DMA from protected to non-protected page, check that data is still encrypted
|
|
|
|
|
|
```
|
|
|
dma_attack 0x80f10000 0x80f11000 0x20
|
|
|
read 0x80f11000 0x20
|
|
|
```
|
|
|
|
|
|
1. Modify original data (from CPU, legal)
|
|
|
|
|
|
```
|
|
|
read 0x80f10000 0x20
|
|
|
write 0x80f10000 0xaa 0x20
|
|
|
read 0x80f10000 0x20
|
|
|
```
|
|
|
|
|
|
1. Replay attack by malicious DMA and check (intrusion detected, simulation crash)
|
|
|
|
|
|
```
|
|
|
dma_attack 0x80f11000 0x80f10000 0x20
|
|
|
```
|
|
|
|
|
|
The data in the 0x80f10000-0x80f10020 frange is now corrupted.
|
|
|
|
|
|
1. Read corrupted data from CPU, HSM detects integrity violation and raise interrupt to signal intrusion (in this simple example this crashes the simulation)
|
|
|
|
|
|
```
|
|
|
read 0x80f10000 0x20
|
|
|
```
|
|
|
|
|
|
The console closes and, in the terminal in which we launched the simulation, the HSM prints some debug information about the integrity violation that has been detected:
|
|
|
|
|
|
```
|
|
|
----------------------------------------------------------------
|
|
|
INTEGRITY VIOLATION DETECTED, ABORTING (cycle 116086520)...
|
|
|
----------------------------------------------------------------
|
|
|
ERROR : HASH INTEGRITY READ OPERATION
|
|
|
parent address : 81000400
|
|
|
set address : 80f10000
|
|
|
pspe address : 91008000
|
|
|
hash : 10f57a81
|
|
|
hash : 97e0025e
|
|
|
reference hash : 3f3ea572
|
|
|
reference hash : 1df2c2b5
|
|
|
set : eedab0e0
|
|
|
set : 7af87ec4
|
|
|
set : 9e5a7313
|
|
|
set : 47ff8a17
|
|
|
set : 4ffeefca
|
|
|
set : d412ce12
|
|
|
set : 5148b8aa
|
|
|
set : f920362f
|
|
|
set : b8fb9b2a
|
|
|
set : f5d614ac
|
|
|
set : f3ca48e9
|
|
|
set : 6db0ab62
|
|
|
'sc_stop' function was called. Exit code : 1
|
|
|
Bye!
|
|
|
```
|
|
|
|
|
|
[downloads section]: downloads
|
|
|
|
|
|
<!-- vim: set tabstop=4 softtabstop=4 shiftwidth=4 noexpandtab textwidth=0: --> |