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.
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:
If you prefer the SystemCASS way, please download it from its Subversion repository and install it:
export SYSTEMC=<path-to-systemcass-installation-directory>svn co https://www.soclib.fr/svn/systemcass /tmp/systemcasscd /tmp/systemcass/source./bootstrap./configure --prefix=$SYSTEMCmakemake installcd$SYSTEMCln-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:
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:
tar zxf secbus.XXXXXXXXXX.tgzcd secbusexport 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/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
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.
Compile the virtual prototype:
make -C$SECBUS vp-<arm|mips>
Compile the software stack:
make -C$SECBUS sw-<arm|mips>
Launch the simulation:
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:
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:
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:
Type help <command> to get some help about them:
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 - 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).