Atomic Cryptography Extension (ACE)

The Atomic Cryptography Extension (ACE) is being developed by the RISC-V High Assurance Cryptography (HAC) Task Group.

ACE is an Instruction Set Architecture (ISA) extension that provides atomic (i.e., full-round) cryptographic operations using Cryptographic Contexts (CCs). A Cryptographic Context is an indivisible data structure consisting of metadata and a content section that holds secrets such as keys. The metadata binds secrets to a specific cryptographic algorithm and defines usage and access policies, preventing use with other algorithms and, optionally, by unauthorized processes, security states, or other entities.

CCs take one of two forms:

1. In protected architectural containers called Cryptographic Registers (CRs), which conceal the secrets once these are written in the CRs together with their metadata. The architecture provides no mechanism to export the secrets in a CR as plaintext.

2. As Sealed Cryptographic Contexts (SCCs) in untrusted memory, encrypted using a mode of operation of Authenticated Encryption with Associated Data (AEAD). A SCC can be reimported into a CR.

ACE instructions can use keys only while they reside in a CR. When a CC is stored in memory as a SCC, the binding between the key and its metadata relies on the cryptographic strength of the AEAD encryption.

SCCs may be produced by trusted software or hardware and supplied to applications. Any piece of software can create its own Cryptographic Contexts by writing a key and metadata into a Cryptographic Register. The original key can then be erased from system memory to reduce exposure while ACE continues to operate using the key secured within the register.

The metadata may specify anything from a basic cipher (e.g., AES-128 or AES-256) to a mode of operation such as SM4-GCM-SIV. A key advantage of ACE is that a small set of algorithm-agnostic instructions can support many algorithms, since the metadata selects the algorithm to execute. As a result, the same compiled binary can target any 128-bit cipher in a given mode (e.g., AES-GCM-SIV, SM4-GCM-SIV, Калина-GCM-SIV, or Кузнечик-GCM-SIV); only the CC changes, not the instruction sequence.

The current ACE interface supports only symmetric cryptographic primitives; however, the ISA easily supports asymmetric cryptography, if public key operations are specified as algorithms which can be selected by the metadata.

License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the LICENSE 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.

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-high-assurance-cryptography.git

Building the Documentation

To start the build process, run:

cd ./riscv-high-assurance-cryptography && 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 command can be run:

pip3 install pre-commit && pre-commit install

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

pre-commit run --all-files