scarv / xcrypto-ref

XCrypto: a cryptographic ISE for RISC-V

XCrypto: reference implementation

Acting as a component part of the SCARV project, XCrypto is a general-purpose Instruction Set Extension (ISE) for RISC-V that supports software-based cryptographic workloads. The main repository acts as a general container for associated resources; this specific submodule houses a formally verified, area-optimised reference implementation of XCrypto that (e.g., acting as a co-processor) can be coupled to existing RISC-V cores.

Organisation

├── bin                     - scripts (e.g., environment configuration)
├── build                   - working directory for build
├── doc                     - documentation
│   ├── tex                   - LaTeX content
│   └── image                 - image content
├── example                 - example programs
│   ├── common                - Shared files between examples
│   ├── ...                   - Multiple cryptographic algorithm examples
│   └── integration-test      - "Hello World" example integration program
├── extern                  - external resources (e.g., submodules)
│   ├── libscarv              - submodule: scarv/libscarv
│   ├── picorv32              - submodule: cliffordwolf/picorv32
│   ├── riscv-opcodes         - submodule: scarv/riscv-opcodes
│   └── texmf                 - submodule: scarv/texmf
├── flow                    - simulation and implementation flow
│   ├── gtkwave               - wave views
│   ├── benchmarks            - performance benchmarking flow
│   ├── verilator             - subsystem simulator flow
│   ├── icarus                - simulation flow
│   └── yosys                 - formal SMT2 generation and synthesis
├── rtl                     - implementation
│   ├── coprocessor           - reference implementation
│   └── integration           - reference integration (with `picorv32`)
└── verif                   - verification flow
    ├── formal                - Formal verification checks
    ├── tb                    - Simulation/integration/formal testbenches
    └── unit                  - Simulation sanity tests

Quickstart

• The releases page houses pre-built content.

• You can build the content yourself:

  1. Install any associated pre-requisites, e.g.,

     • the Yosys Verilog synthesis tool, exporting the YOSYS_ROOT environment variable st. ${YOSYS_ROOT}/yosys points at the Yosys executable,
     • the Verilator Verilog simulator tool, exporting the VERILATOR_ROOT environment variable st. ${VERILATOR_ROOT}/bin/verilator points at the Verilator executable,
     • the SCARV-specific fork of the official RISC-V toolchain, exporting the RISCV environment variable st. ${RISCV}/bin/riscv64-unknown-elf-gcc points at the GCC executable,
     • a modern LaTeX distributation, such as TeX Live, including any required packages.

  2. Execute

     git clone https://github.com/scarv/xcrypto-ref.git
     cd ./xcrypto-ref
     git submodule update --init --recursive
     source ./bin/conf.sh

     to clone and initialise the repository, then configure the environment; for example, you should find that the environment variable REPO_HOME is set appropriately.

  3. Use targets in the top-level Makefile to drive a set of common tasks, e.g.,

     • execute

       make doc

       to build the documentation,

     • execute

       make clean

       to clean-up (e.g., remove everything built in ${REPO_HOME}/build).

Notes

Running Simulations

There are two simulation testbenches for the design. The integration testbench acts as a general ISA simulator, which allows one to write and run C code on a PicoRV32 CPU attatched to the reference XCrypto implementation. The second is only for testing during design and implementaton of the RTL, and will be of little interest to those wanting to write code for the ISE.

Integration Tests

These tests work as part of an example integration of the COP with the picorv32 core. The integrated design subsystem is found in rtl/integration. It can be used to write experimental / development code without having to have an actual hardware platform on which to implement the reference design.

Information on how to build and use the simulation binary is found in $REPO_HOME/flow/verilator/README.md.

Example code to run in the integration testbench is found in examples/integration-test

Benchmarking

The integration testbench described in $REPO_HOME/flow/verilator/README.md is also used to run the benchmarking programs. More information on the benchmarking flow can be found in $REPO_HOME/flow/benchmarks/README.md.

Unit Tests

• These use icarus verilog, and the modified binutils to run the tests found in verif/unit/.
• These are not correctness/compliance tests. They are used as simple sanity checks during the design cycle.
• Checking for correctness should be done using the formal flow.

Building the testbench:

$> make unit_tests      # Build the unit tests
$> make icarus_build    # Build the unit test simulation testbench

Running the tests:

$> make icarus_run SIM_UNIT_TEST=<file> RTL_TIMEOUT=1000
$> make icarus_run_all  # Run all unit tests as a regression

The <file> path should point at a unit-test hex file, present in $XC_WORK/unit/*.hex. Using $XC_WORK as part of an absolute path to the hex file is advised.

Formal testbench

Formal checks are run using Yosys and Boolector. Checks are listed in verif/formal/*. A more complete description of the formal flow can be found toward the end of the implementation document.

To run a single check, use:

$> make yosys_formal FML_CHECK_NAME=<name>

where <name> corresponds too some file called verif/formal/fml_check_<name>.v.

To run a regression of formal checks:

$> make -j 4 yosys_formal

will run 4 proofs in parallel. Change this number to match the available compute resources you have. One can also run a specfic subset of the available formal checks by delimiting the check names with spaces, and using a backslash to escape the spaces: FML_CHECK_NAME=check1\ check2\ check3.

Acknowledgements

This work has been supported in part by EPSRC via grant EP/R012288/1, under the RISE programme.

xcrypto-ref's Issues

Example code demonstrations

Showing the worth of the ISE depends on creating example programs which accelerate existing cryptographic algorithms with the ISE instructions. This thread collects ideas for algorithms or kernels which would make for good examples.

• AES
• Multi-precision arithmetic
• PRESENT - 4-bit sbox
• PRINCE - 4-bit sbox
• Frodo - seems trivial to just utilise the 16-bit packed arithmetic
• Keccak / SHA3
  • KeccakP-400. Performance dominated by address index computations rather than state computations. ~12.5% speedup using trivial translation of RISC-V sequences to XCrypto sequences. No register occupancy optimisations done yet. Tried to keep code density the same.
  • KeccakP-1600. 36% speedup. Much faster 64-bit rotations than basic RISC-V. Remaining performance gains in non-unrolled code to come from address computation.
• ChaCha
• Modular Exponentiation

Timing optimisations

A collection of timing optimisations to implement.

• Change instruction class id_class to a 1-hot signal`.
• Widen the id_sclass signal.
  • Recode the SCLASS_* instruction encodings to carry more information about the instructions.

BRAM/DMEM register file

50% of the LUTs and 66% of FFs in the implementation are down to a BRAM/DMEM unfriendly register file implementation.

• Parameter switch to implement a BRAM based register file
• Implement a BRAM /DMEM friendly register file.

Signed offset (dis)assembly

Currently the checks for valid/invalid signed offsets for loads and stores do not work when assembling, and the disassembler does not print them correctly either.

Replace naive LUT based AES SBOX[-1] implementation

• Should really use something like the Canright SBOX implementation.

Permutation Instruction Modification

Somewhere to track changes to the reference XCrypto implementation pertaining to scarv/xcrypto-spec#22

Todo:

• Decoder:
  • Remove xc.pperm.* decode lines
  • Add bmv, pbit, ipbit and pbyte decode lines
  • Rename twiddle instruction class to permute, using it to referr to the pbit,ipbit,pbyte instructions.
  • Put bmv in the bitwise class with ins and ext
• Permute FU
  • Add a new functional unit which implements only the permute instruction class.
• Packed ALU
  • Remove xc.pperm.* implementations
  • Add bmv implementation.