Just remembered that the PDDB is *locked* to a given device. To restore to a new device, you have to unlock all the Bases, and re-encrypt them to the new device's DNA. This commit adds the facilities to detect this condition, but the actual code to do this is quite involved...let's handle that after we've got a "simple" restore to the same device going. Why do we lock to a device's DNA? the idea is to prevent attacks where people are taking static blocks of crypto data and just swapping it between devices to see if they can get something to decrypt. It also makes it harder for an adversary to replace the physical device -- e.g., an evil maid prepared a replacement with implants in advance, and they image your PDDB onto the replaced device, hoping that you don't notice. Because the PDDB is device-locked, the "evil maid" would have to forge the devices DNA to match yours: possible, but would require kernel mods that patch over the reported ID; that would trigger the line across the top of the screen; or, somehow editing the FPGA itself to force its device ID to report the same as yours. This last attack vector would be successful, but afaik there is no known way to modify an FPGA's DNA code. I'm sure there is some proprietary secret know that Xilinx uses to set it, and if you were a large government you may be able to coerce Xilinx into giving you those codes plus some tool that could set the fuses plus some unfused devices (the fuses are burn-once) but.... |
||
|---|---|---|
| .cargo | ||
| .github/workflows | ||
| .vscode | ||
| apps | ||
| devkey | ||
| docs | ||
| emulation | ||
| imports | ||
| kernel | ||
| LICENSES | ||
| loader | ||
| locales | ||
| precursors | ||
| services | ||
| svd2repl | ||
| svd2utra | ||
| tools | ||
| utralib | ||
| xous-ipc | ||
| xous-rs | ||
| xtask | ||
| .gitattributes | ||
| .gitignore | ||
| analyze-bloat.sh | ||
| API.md | ||
| buildpush.ps1 | ||
| buildpush.sh | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| README.md | ||
| RELEASE-v0.8.md | ||
| RELEASE-v0.9.md | ||
| rustfmt.toml | ||
| start-gdb.sh | ||
| wb-gdb.sh | ||
Xous Core
Core files for the Xous microkernel operating system.
You might find this wiki handy, as well as the Xous Book.
This repository contains everything necessary to build the Xous kernel from source. It consists of the following projects:
- kernel: core memory manager, irq manager, and syscallhandler
- loader: initial loader used to start the kernel
- tools: programs used to construct a final boot image
- docs: documentation on various aspects of Xous
- emulation: Renode scripts used to emulate Xous
- xous-rs: userspace library
Dependencies
- Xous requires its own Rust target,
riscv32imac-unknown-xous-elf. If you runcargo xtaskfrom the command line, you should be prompted to install the target automatically if it does not already exist. - You may need to remove the
target/directory before building, ifrustccontinues to behave like it can't find thexoustarget even after it is installed. - If you plan on doing USB firmware updates, you'll need
progressbar2(updates) andpyusb(updates). Note thatpyusbhas name space conflicts with similarly named packages, so if updates aren't working you may need to create avenvor uninstall conflicting packages. - If you are doing development on the digital signatures with the Python helper scripts, you will need:
pycryptodome(signing - PEM read),cryptography(signing - x509 read),pynacl(signing - ed25519 signatures) (most users won't need this). - Some system packages are needed, which can be installed with
sudo apt install libssl-dev libxkbcommon-devor similar - If you receive an error about
feature resolver is required, try installing a newer version ofrustcandcargovia rustup
Quickstart using Hosted Mode
You can try out Xous in a "hosted mode" wherein programs are compiled for your native platform and are run locally as processes within your current operating system. System calls are replaced with network calls to a kernel that simply shuffles messages around.
Xous uses the xtask convention,
where various complex build commands are stored under cargo xtask.
This allows for us to create arbitrarily complex build sequences
without resorting to make (which is platform-dependent),
sh (which requires a lot of external tooling), or another build
system.
To build a set of sample programs and run them all using the kernel for communication, clone this repository and run:
cargo xtask run
This will build several servers and a "shell" program to control them
all. Most notably, a graphics-server will appear and kernel messages
will begin scrolling in your terminal.
Quickstart using an emulator
Xous uses Renode as the preferred emulator, because it is easy to extend the hardware peripherals without recompiling the entire emulator.
Download Renode and ensure it is in your path.
For now, you need to download the nightly build,
until DecodedOperation is included in the release.
Then, build Xous:
cargo xtask renode-image
This will compile everything in release mode for RISC-V, compile the tools
require to package it all up, then create an image file.
Finally, run Renode and specify the xous-release.resc REnode SCript:
renode emulation/xous-release.resc
Renode will start emulation automatically, and will run the same set of programs as in "Hosted mode".
Generating a hardware image
To build for real hardware, you must specify an .svd file. This
file is generated by the SoC build process and describes a single
Betrusted core. These addresses will change as hardware is modified,
so if you distribute a modified Betrusted core, you should be sure
to distribute the .svd file.
We have included a reference version of the gateware and its SVD
file in the precursors directory, so you can compile a gateware
for the reference image using this command:
cargo xtask hw-image precursors/soc.svd
The resulting images are in your target directory (typically target/riscv32imac-unknown-xous-elf/release/)
with the names xous.img (for the kernel) and loader.bin (for its bootloader). The corresponding
gateware is in precursors/soc_csr.bin. These can be written to your
device by following the update guide.