kbroch-rivosinc/riscv-cfi

This repo holds the work area and revisions of the RISC-V CFI (Shadow Stack and Landing Pads) specifications. CFI defines the privileged and unprivileged ISA extensions that can be used by privileged and unprivileged programs to protect the integrity of their control-flow.

RISC-V CFI specification

This document is capturing discussions at the Shadow Stacks and Landing Pads TG and attempts to document the baseline. This is not official specification and everything in this document may change. Control-flow Integrity (CFI) provides CPU instruction set architecture (ISA) capabilities to defend against Return-Oriented Programming (ROP) and Call/Jump-Oriented Programming (COP/JOP) style control-flow subversion attacks.

To enforce backward edge control-flow integrity, the extension introduces a shadow stack. To enforce forward edge control-flow integrity, the extension introduces labeled landing pad instructions.

License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the LICENSE file.

Maintainers

The list of maintainers of this specification is maintained in the MAINTAINERS file.

Contributors

The list of contributors to this specification is maintained in the contributors file.

For guidelines on how to contribute, refer to the CONTRIBUTING file.

Governance

The governance for this project is defined in the GOVERNANCE file.

Community information, including meeting (if held) and mailing lists are detailed in this file.

Building the Document

Directory Structure

The following directories are used to organize the contents of this repo:

• dependencies/: software dependencies needed to build the specification

• docs-resources/: resources for all specifications sourced from git submodule

• src/: source files for the specification

• build/: default directory where the build artifacts are generated

Prerequisites

To build the document, you’ll need the following tools installed on your system:

• Make

• asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical

• Docker

Cloning the Repository

git clone --recurse-submodules https://github.com/riscv/riscv-cfi.git

Building the Documentation

To start the build process, run:

cd ./riscv-cfi && make build

The Makefile script will check the availability of Docker on your system:

• If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems.

• If Docker is not available, the documentation will be built directly on your system using the installed tools.

The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the HEADER_SOURCE variable in the Makefile.

The build process utilizes several options, including theming and font settings, and generates a PDF document as output.

Cleaning up

To clean up the generated files, run:

make clean

Enabling pre-commit checks locally

The repository has some basic commit checks set up with pre-commit that will be enforced by the GitHub CI. To ensure these checks are also run in the local repository while making changes the following can be done:

Installing pre-commit tool

# Do once on your system
pip3 install pre-commit

Installing pre-commit git hook in repo

# Do once in local repo
pre-commit install

Rather than doing the above pre-commit install in every repo that uses it, you can do it once on your system.

When enabling additional checks by editing .pre-commit-config.yaml, it is recommended running the newly added check on all files in the repository. This can be done with the following command:

Running all pre-commit hooks on all files

pre-commit run --all-files