University of Cambridge, SRI International, Digital Catapult
This is a living document with frequently asked questions regarding Capability Hardware Enhanced RISC Instructions (CHERI). The document aims to help people get started with experimenting with CHERI hardware-software stacks, including Arm Morello and CHERI-RISC-V.
CHERI-related competition participants (e.g., Digital Security by Design Technology Access Programme (DSbD TAP), Defence and Security Accelerator (DASA)) might find this document useful when exploring their project prototype ideas.
We encourage anyone interested in improving this document to make contributions to it, e.g. by adding a new question or extending an answer. See How can I contribute to this document? for more information.
- What is CHERI?
- What types of threat has CHERI been designed to prevent?
- What CHERI-extended hardware is available to use?
- How can I get an Arm Morello board?
- How can I emulate a CHERI-enabled environment?
- How can I build and emulate a CHERI-enabled environment?
- Where are cheribuild.py images and build files stored?
- Can I build a custom CheriBSD branch using cheribuild.py?
- Can I develop baremetal applications for Arm Morello?
- Operating systems
- Software porting
- What programming languages can I use on CHERI?
- Can I use Python with CHERI?
- Is my software safer just by running it on a CHERI-extended CPU?
- What are the pure-capability and hybrid ABIs?
- Should I compile my code for the pure-capability or hybrid ABI?
- How easy it is to compile C/C++ code for the pure-capability ABI?
- Can I link CHERI C/C++ code compiled for the pure-capability ABI and the hybrid ABI?
- What software has been ported to CHERI?
- How can I print a CHERI capability in CHERI C/C++?
- How can I display a CHERI capability in GDB-CHERI?
- How can I upgrade CheriBSD?
- How can I build CheriBSD from source code?
- Does CheriBSD implement spatial safety (e.g., to prevent out-of-bounds bugs)?
- Does CheriBSD implement temporal safety (e.g., to prevent use-after-free bugs)?
- How can I switch to another CheriBSD kernel (e.g., a pure-capability kernel)?
- Is there any IDE for CheriBSD?
CHERI (Capability Hardware Enhanced RISC Instructions) is a joint research project by SRI International and the University of Cambridge to revisit fundamental design choices in hardware and software to dramatically improve system security. An Introduction to CHERI provides a high-level introduction to CHERI.
CHERI enables fine-grained memory protection (e.g. to prevent out-of-bounds and use-after-free bugs) and highly scalable software compartmentalization (e.g. to mitigate future or unknown vulnerabilities in third-party software).
Arm Morello is currently the only System-on-Chip with a CHERI-extended CPU.
Additionally, CHERI-RISC-V and Morello can be emulated using QEMU-CHERI or Morello FVP.
Go to the Digital Security by Design website and follow the instructions there.
You can use pre-compiled Docker images from Docker Hub that include a ready-to-use QEMU-based CheriBSD VM and LLVM to cross-compile code:
Download a Docker image.
For Arm Morello:
docker pull ctsrd/cheribsd-sdk-qemu-morello-purecap
docker pull ctsrd/cheribsd-sdk-qemu-riscv64-purecap
Run a shell in a Docker container. The container will stop once you exit this session.
For Arm Morello:
docker run -ti --rm --name cheribsd-morello \ ctsrd/cheribsd-sdk-qemu-morello-purecap:latest
docker run -ti --rm --name cheribsd-riscv \ ctsrd/cheribsd-sdk-qemu-riscv64-purecap:latest
Run a QEMU-based VM with CheriBSD and use
rootto log in once the
For Arm Morello:
docker exec -ti cheribsd-morello \ /opt/cheri/cheribuild/cheribuild.py run-morello-purecap
docker exec -ti cheribsd-riscv \ /opt/cheri/cheribuild/cheribuild.py run-riscv64-purecap
You can compile code in the QEMU VM, as explained in the Getting Started with CheriBSD guide, or cross-compile it in the Docker container shell session using a compiler in the directory
Clone the cheribuild repository.
Install dependencies for your operating system.
Build a software stack and run CheriBSD in a QEMU-based VM.
For Arm Morello:
cheribuild.py run-morello-purecap -d
cheribuild.py run-riscv64-purecap -d
By default, images built by
cheribuild.py are stored in
$HOME/cheri/output and build files in
cheribuild.py implements several flags to allow you to build multiple CheriBSD branches and store the results separately:
--cheribsd-<target>/source-directory /path/to/your/branchto specify a custom branch's source code directory.
--cheribsd-<target>/build-directory /path/to/your/buildto specify where build files should be stored.
--cheribsd-<target>/install-directory /path/to/your/rootfsto specify where root filesystem files should be installed.
--disk-image-<target>/path /path/to/your/image.imgto specify where a disk image should be stored.
See this example application.
There are several institutions interested in developing seL4 for CHERI. You can talk to them in the
#sel4channel at the CHERI-CPU Slack.
Check the CHERI OS-feature matrix to compare CheriBSD and Morello Linux.
At the moment, CheriBSD is the most fully featured operating system running on CPUs with CHERI extensions. It also provides a large number of pre-compiled third-party software dependencies that you can simply install with package managers for your project. If you intend to work with code that runs on UNIX-like operating systems, we recommend you to start with CheriBSD.
Follow the Getting Started with CheriBSD guide and do not skip any section.
The guide has been structured to make you aware of actions you should take before trying to use CheriBSD. Of critical importance, you should upgrade your Morello board firmware before installing CheriBSD.
Currently, the most mature programming languages for CHERI are CHERI C and CHERI C++.
See the CHERI C/C++ Programming guide for more information.
There is an ongoing project at the University of Kent to add support for CHERI in Rust.
There are no interpreters that support CHERI for these programming languages.
There is no Python interpreter that would run your Python code using capability-aware instructions.
You can use a Python interpreter compiled for a baseline architecture but it does not give you any of the security benefits of a CHERI-enabled CPU.
No. While an operating system (i.e., a kernel, basic programs and libraries shipped with the OS) might be compiled for the pure-capability ABI and hence prevent memory-safety bugs in its components, code compiled for a baseline architecture (e.g., AArch64 for Morello, RISC-V for CHERI-RISC-V) does not benefit from security features of CHERI.
You must compile your code to explicitly use CHERI capabilities to access memory either by compiling it for the pure-capability ABI or the hybrid ABI with appropriate data type qualifiers that indicate the intention of using CHERI capabilities in place of legacy C pointers (in case of C/C++).
The pure-capability ABI (also known as CheriABI in CheriBSD and PCuABI in Linux and Android) is a new process ABI that uses only CHERI capabilities to access memory and interact with a kernel.
The hybrid ABI allows a process to access memory using legacy pointers and CHERI
When compiling such C/C++ code, a pointer must be annotated with the
__capability type qualifier to use a CHERI capability instead of a legacy
Both pure-capability and hybrid CheriBSD kernels support the pure-capability and hybrid ABIs at the same time. You can also switch between pure-capability and hybrid CheriBSD kernels without replacing user-space programs and libraries.
In most cases, porting software to the pure-capability ABI is straightforward and does not heavily disrupt code. For example, the Capabilities Limited company shows in their report Assessing the Viability of an Open-Source CHERI Desktop Software Ecosystem that they needed to modify 0.026% lines of code in around 6 million lines of code from KDE, Qt, X11 for CheriABI to run KDE Plasma on top of Xvnc on CheriBSD.
It might seem that compiling code for the hybrid ABI is a better approach to port software to CHERI than compiling it for the pure-capability ABI because you can incrementally introduce CHERI capabilities in your code, and not worry about all incompatibilities with CHERI at once.
However, when using the hybrid ABI, you have to annotate all pointers as CHERI capabilities, and still you will not have any guarantees that there are no legacy pointers left. Additionally, all third-party libraries that your code depends on will not use CHERI capabilities, unless you change them as well.
The LLVM-CHERI assists a developer in C/C++ code porting to CHERI C/C++ by printing appropriate warnings whenever it encounters incompatibilities between C/C++ and CHERI C/C++ semantics. In many cases, it is sufficient to only fix compile-time issues to successfully run a program compiled for the pure-capability ABI.
However, programming language interpreters, Just-in-Time compilers and other software that embeds metadata in pointers, implements custom memory allocators or performs other non-trivial pointer manipulations can cause run-time issues that must be investigated using a debugger. A user can examine these issues with the GDB-CHERI debugger that can disassemble capability-specific CPU instructions and display properties of CHERI capabilities, including their validity, stored in registers and in memory.
See the CHERI C/C++ Programming guide for example compiler warnings and solutions to them, and the Getting Started with CheriBSD guide for an example CheriABI "Hello World" – how to compile and debug it.
No. LLVM-CHERI does not allow to link a program for one ABI with libraries compiled for another ABI.
For CheriBSD, there are ~9,000 pre-compiled CheriABI packages, including KDE Plasma 5, Git, Rsync, sudo, Bash, tmux. Besides that, there are ~24,000 hybrid ABI packages, including LLVM-CHERI, GDB-CHERI, Chromium, Firefox, Vim, Python, Meson, Ninja.
You can list all available software on CheriBSD with
pkg64c rquery %n and
pkg64 rquery %n.
Alternatively, you can search for a specific package using
pkg64c search <pattern> and
pkg64 search <pattern>.
You can browse CheriABI and hybrid ABI package repositories at pkg.cheribsd.org.
You can also store a formatted string with properties of a CHERI capability using strfcap(3).
wiki page for
Library-based compartmentalization in CheriBSD
Available for Morello in the 22.12 release.
Colocation in CheriBSD
Available for CHERI-RISC-V in the cocalls branch.
There are plans to make this model available for Morello as well.
Currently, there are no binary upgrades for CheriBSD.
The only way to upgrade a CheriBSD host is to build and install CheriBSD from source code. See the wiki page for instructions how to do this. Note that we cannot guarantee stability when upgrading CheriBSD and it is important to make sure you can recover your data if an upgrade fails.
You have two choices:
Build and install CheriBSD natively on Arm Morello using these instructions
Cross-compile (on FreeBSD, macOS or Linux) CheriBSD for CHERI-RISC-V or Arm Morello using cheribuild
The official CheriBSD release runs basic programs and libraries compiled for the pure-capability ABI and a hybrid kernel.
It also includes a pure-capability kernel in
to find out how to do that.
Currently, the official CheriBSD release does not include temporal safety mechanisms. This feature (also known as Cornucopia in CheriBSD) is scheduled for a future release and can be used today by installing a Cornucopia-enabled kernel and revocation-aware memory allocators.
See the Cornucopia tutorial to read more how to use it.
Use one of the following methods:
nextboot -k KERNCONF
See nextboot(8) for more details.
See loader.conf(5) for more details.
In a boot loader, press
5multiple times to select
KERNCONF is a name of a directory in the
/boot directory with a kernel
kernel.GENERIC-MORELLO-PURECAP) that corresponds to a kernel
configuration file from CheriBSD source code (e.g.,
No. The closest to it is Kate Editor but it is still far from an actual IDE.
Alternatively, if your question is related to Linux or Android for Arm Morello, you can join the Morello Forum.
If you are not sure what is a cause of your issue, you can contact us first, as described above.
Issues related to LLVM-CHERI but not specific to Morello should be reported here.
In order to add a new question: