CHERI Frequently Asked Questions

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.

Contributions

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.

License

The CHERI FAQ repository is released under the CC BY 4.0 license.

Contents

General

What is CHERI?

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.

What types of threat has CHERI been designed to prevent?

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).

What CHERI-extended hardware is available to use?

Arm Morello is currently the only System-on-Chip with a CHERI-extended CPU.

There are several CHERI-RISC-V prototypes on FPGA, including a superscalar, out-of-order CHERI-Toooba core extending Toooba that is based on RiscyOO.

Additionally, CHERI-RISC-V and Morello can be emulated using QEMU-CHERI or Morello FVP.

How can I get an Arm Morello board?

Go to the Digital Security by Design website and follow the instructions there.

How can I emulate a CHERI-enabled environment?

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:

  1. Download a Docker image.

    • For Arm Morello:

      docker pull ctsrd/cheribsd-sdk-qemu-morello-purecap

    • For CHERI-RISC-V:

      docker pull ctsrd/cheribsd-sdk-qemu-riscv64-purecap

  2. 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

    • For CHERI-RISC-V:

      docker run -ti --rm --name cheribsd-riscv \
    ctsrd/cheribsd-sdk-qemu-riscv64-purecap:latest

  3. Run a QEMU-based VM with CheriBSD and use root to log in once the login: prompt appears.

    • For Arm Morello:

      docker exec -ti cheribsd-morello \
    /opt/cheri/cheribuild/cheribuild.py run-morello-purecap

    • For CHERI-RISC-V:

      docker exec -ti cheribsd-riscv \
    /opt/cheri/cheribuild/cheribuild.py run-riscv64-purecap

  4. 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 /opt/cheri/output/morello-sdk/bin/.

How can I build and emulate a CHERI-enabled environment?

  1. Clone the cheribuild repository.

  2. Install dependencies for your operating system.

  3. Build a software stack and run CheriBSD in a QEMU-based VM.

    • For Arm Morello: cheribuild.py run-morello-purecap -d

    • For CHERI-RISC-V: cheribuild.py run-riscv64-purecap -d

Where are cheribuild.py images and build files stored?

By default, images built by cheribuild.py are stored in $HOME/cheri/output and build files in $HOME/cheri/build.

Can I build a custom CheriBSD branch using cheribuild.py?

Yes. 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/branch to specify a custom branch's source code directory.
  • --cheribsd-<target>/build-directory /path/to/your/build to specify where build files should be stored.
  • --cheribsd-<target>/install-directory /path/to/your/rootfs to specify where root filesystem files should be installed.
  • --disk-image-<target>/path /path/to/your/image.img to specify where a disk image should be stored.

Can I develop baremetal applications for Arm Morello?

See this example application.

Operating systems

What operating systems are being developed for CHERI?

Which operating system should I use to experiment with CHERI?

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.

How do I get started with CheriBSD on Morello?

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.

Software porting

What programming languages can I use on CHERI?

  • CHERI C/C++

    Currently, the most mature programming languages for CHERI are CHERI C and CHERI C++.

    See the CHERI C/C++ Programming guide for more information.

  • Rust

    There is an ongoing project at the University of Kent to add support for CHERI in Rust.

  • Python/Ruby/Lua/JavaScript/...

    There are no interpreters that support CHERI for these programming languages.

Can I use Python with CHERI?

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.

Is my software safer just by running it on a CHERI-extended 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++).

What are the pure-capability and hybrid ABIs?

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 capabilities. 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 pointer.

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.

See the CheriABI paper and the PCuABI specification for more information on the ABIs.

Should I compile my code for the pure-capability or hybrid ABI?

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.

There are still some situations when choosing the hybrid ABI over the pure-capability ABI has benefits. In case of extremely large code bases (e.g., the Chromium browser and its dependencies), you might want to compartmentalize parts of your code base now (e.g., the V8 JavaScript engine in Chromium), parts that are known for security vulnerabilities with significant impacts, rather than spend a lot of time trying to port the whole project for the pure-capability ABI and then compartmentalize it.

How easy it is to compile C/C++ code for the pure-capability ABI?

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.

What software has been ported to CHERI?

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.

The packages are built using CheriBSD ports, a fork of FreeBSD ports that includes a collection of ~32,000 third-party software ports for FreeBSD.

See the Getting Started with CheriBSD guide for more information on third-party software packages, and the CheriBSD Ports and Packages article to read more on the package building process.

How can I print a CHERI capability in CHERI C/C++?

See the Displaying Capabilities wiki page for printf(3) string formats.

You can also store a formatted string with properties of a CHERI capability using strfcap(3).

How can I display a CHERI capability in GDB-CHERI?

See the Displaying Capabilities wiki page for print command output formats.

Compartmentalization

What compartmentalization models are available for CHERI?

CheriBSD

How can I upgrade CheriBSD?

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.

How can I build CheriBSD from source code?

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

Does CheriBSD implement spatial safety (e.g., to prevent out-of-bounds bugs)?

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 /boot/kernel.GENERIC-MORELLO-PURECAP. See these instructions to find out how to do that.

Does CheriBSD implement temporal safety (e.g., to prevent use-after-free bugs)?

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.

How can I switch to another CheriBSD kernel (e.g., a pure-capability kernel)?

Use one of the following methods:

  • Run nextboot -k KERNCONF

    See nextboot(8) for more details.

  • Add kernel="KERNCONF" to /boot/loader.conf

    See loader.conf(5) for more details.

  • In a boot loader, press 5 multiple times to select KERNCONF

KERNCONF is a name of a directory in the /boot directory with a kernel (e.g., kernel.GENERIC-MORELLO-PURECAP) that corresponds to a kernel configuration file from CheriBSD source code (e.g., GENERIC-MORELLO-PURECAP).

Is there any IDE for CheriBSD?

No. The closest to it is Kate Editor but it is still far from an actual IDE.

Community

Join the CHERI-CPU Slack workspace or the cl-cheri-discuss mailing list and ask questions there.

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.

How can I contribute to this document?

In order to add a new question:

  1. Create a fork of the CHERI FAQ repository.

  2. Add your question and answer to a file in src/questions/.

  3. Create a pull request in the CTSRD-CHERI/cheri-faq repository with your change.