aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md163
1 files changed, 103 insertions, 60 deletions
diff --git a/README.md b/README.md
index 6d813ef..e2c10a8 100644
--- a/README.md
+++ b/README.md
@@ -1,80 +1,127 @@
-STM32 software for dev-bridge/Alpha board
-=========================================
+STM32 firmware for Cryptech Alpha board
+=======================================
-The dev-bridge board is a daughterboard for the Novena, which talks to the
-Novena's FPGA through the high-speed expansion connector.
+The Alpha board is our first full prototype for an open-source hardware
+security module (HSM). It is a custom board with an STM32 Cortex-M4
+microcontroller and an Artix-7 FPGA, flash-based keystore, separate memory
+for the Key Encryption Key, etc. See the `hardware` repository for
+schematics and production files. See the wiki for design documents.
-The Alpha board is a stand-alone board with an Artix-7 FPGA, a STM32 Cortex-M4
-microcontroller, two USB interfaces etc.
-
-See user/ft/stm32-dev-bridge/hardware/rev01 for schematics of the bridge
-board. There will be more information on the wiki shortly.
+The code in this repository builds the firmware that provides the HSM
+functionality on the Alpha board.
+There is some residual code here to support the "dev-bridge" board, a
+daughterboard for the Novena, which talks to the Novena's FPGA through the
+high-speed expansion connector. Only a few of these boards were ever made,
+and all development/testing ceased as soon as the Alpha became available,
+so the dev-bridge should be considered deprecated, and support may be
+removed in the future.
Copyrights
==========
The license for all work done on this in the CrypTech project is a
-3-clause BSD license (see LICENSE.txt for details). Some files have
-been generated using the STMicroelectronics initialization code
-generator STM32CubeMX and thus have additional copyright header(s).
+3-clause BSD license.
+
+Third-party components, as well as code generated using the
+STMicroelectronics initialization code generator STM32CubeMX, or adapted
+from STM example/support code, may have different licensing, detailed
+below.
+
+Components
+==========
+
+Libraries
+---------
+
+* `mbed` - A stripped down copy of the ARM CMSIS library, copied from the
+ mbed github (see `libraries/mbed/README.txt` for details). The bulk of
+ this library is covered under 3-clause BSD licenses from either ARM or
+ STMicroelectronics, but one file is covered under an Apache license from
+ ARM.
+
+* `libhal` - Build directory for our own Hardware Adaption Library
+ (hardware-independent Cryptech components). Source is expected to be in
+ `sw/libhal`.
+
+* `libtfm` - Build directory for "Tom's Fast Math", which is used heavily
+ for bignum math in the RSA and ECDSA code. This code is covered under an
+ unrestricted public domain license, and source is expected to be in
+ `sw/thirdparty/libtfm`.
+
+* `libcli` - Build directory for a third-party Command Line Interface
+ library. The source is not currently under `sw/thirdparty` because the
+ license is LGPLv2.1; we are negotiating to see if we can get a
+ BSD-compatible license for it.
+
+* `libprof` - A port of the `gmon` profiling package, to be used in
+ development only, not in production code (obviously). The licensing is a
+ mix of BSD and "Cygwin license", which now seems to be LGPLv3.
+
+Projects
+--------
-The "Noise generator" and "Amplifier" parts of the circuit diagram are
-copied from Benedikt Stockebrand's ARRGH project. ARRGH copyright
-statement is included in LICENSE.txt.
+These directories build different firmware images for the Alpha board.
-A stripped down copy of the ARM CMSIS library version 3.20 is included
-in the Drivers/CMSIS/ directory. Unused parts (and documentation etc.)
-have been removed, but every attempt have been made to keep any
-licensing information intact. See in particular the file
-Drivers/CMSIS/CMSIS END USER LICENCE AGREEMENT.pdf.
+* `hsm` - Firmware providing HSM functionality. Clients communicate via
+ RPC requests on the USER USB port, or interactively on the MGMT USB
+ port.
-A full copy of the STM32F4xx HAL Drivers is included in the
-Drivers/STM32F4xx_HAL_Driver/ directory.
+* `bootloader` - The first thing that runs on the device. It either starts
+ the primary firmware, or installs new firmware.
+* `board-test` - Tests of hardware components.
+
+* `cli-test` - Test of the CLI itself, plus some interactive tests of
+ hardware components. Duplicates way too much of the HSM CLI.
+
+* `libhal-test` - A framework for running the libhal component
+ tests. Hasn't been run in a while, probably still works.
Building
========
-The following packages need to be installed (on Ubuntu 14.04):
+Our primary build environments are Debian and Ubuntu, but this should work
+on any system with Gnu tools installed.
- apt-get install gcc-arm-none-eabi gdb-arm-none-eabi openocd
+The following packages need to be installed:
-To build the source code, issue "make" from the top level directory
-(where this file is). The first time, this will build the complete STM
-CMSIS library. A subsequent "make clean" will *not* clean away the CMSIS
-library, but a "make distclean" will.
+ $ apt-get install gcc-arm-none-eabi gdb-arm-none-eabi openocd
+The Makefile assumes that all Cryptech repositories have been fetched into
+a canonical directory structure, e.g. `libhal` and `thirdparty` are
+siblings to this directory, under `sw`.
+
+To build the source code, issue `make` from the top level directory
+(where this file is). The first time, this will build the complete STM
+CMSIS library. A subsequent `make clean` will *not* clean away the CMSIS
+library, but a `make distclean` will.
Installing
==========
-Do "bin/flash-target" from the top level directory (where this file is)
+Do `bin/flash-target` from the top level directory (where this file is)
to flash a built image into the microcontroller. See the section ST-LINK
below for information about the actual hardware programming device needed.
-Example loading the bootloader and the led-test firmware to get some LEDs
-flashing:
+Example loading the HSM firmware:
- $ make bootloader board-test
- $ ./bin/flash-target projects/board-test/led-test
- $ ./bin/flash-target projects/bootloader/bootloader
+ $ make hsm
+ $ ./bin/flash-target projects/hsm/hsm
At this point, the STM32 will reset into the bootloader which flashes the
-blue LED five times in one second, and then execution of the LED test
-firmware will begin. The LED test firmware will flash the green, yellow,
-red and blue LEDs in order until the end of time.
+blue LED five times in one second, and then jumps to the primary firmware.
Once the bootloader is installed, regular firmware can be loaded without
an ST-LINK cable like this:
- $ ./bin/dfu projects/board-test/led-test.bin
+ $ cryptech_upload --firmware -i projects/hsm/hsm.bin
Then reboot the Alpha board.
-
ST-LINK
-=======
+-------
+
To program the MCU, an ST-LINK adapter is used. The cheapest way to get
one is to buy an evaluation board with an ST-LINK integrated, and pinouts
to program external chips. This should work with any evaluation board from
@@ -86,7 +133,7 @@ printed on the circuit board. The pin-outs is shown on the circuit board
(follow the thin white line from J1 to the white box with STM32_SWD
written in it). From left to right, the pins are
- 3V3, CLK, GND, I/O, NRST and N/C
+ 3V3, CLK, GND, I/O, NRST and N/C
This matches the pin-out on the DISCO and NUCLEO boards we have tried.
@@ -94,34 +141,30 @@ First remove the pair of ST-LINK jumpers (CN4 on the DISCO, CN2 on the
NUCLEO). Then find the 6-pin SWD header on the left of the STM board (CN2
on the DISCO, CN4 on the NUCLEO), and connect them to the Alpha board:
- NUCLEO / DISCO CRYPTECH ALPHA
- -------------- --------------
-* 1 VDD_TARGET <-> 3V3
-* 2 SWCLK / T_JTCK <-> CLK
-* 3 GND <-> GND
-* 4 SWDIO / T_JTMS <-> IO
-* 5 NRST / T_NRST <-> NRST
-
-N/C (pin 6) means Not Connected.
+ NUCLEO / DISCO CRYPTECH ALPHA
+ -------------- --------------
+ * 1 VDD_TARGET <-> 3V3
+ * 2 SWCLK / T_JTCK <-> CLK
+ * 3 GND <-> GND
+ * 4 SWDIO / T_JTMS <-> IO
+ * 5 NRST / T_NRST <-> NRST
+ * 6 N/C
The Alpha board should be powered on before attempting to flash it.
-
Debugging the firmware
-======================
-
-This site shows several ways to use various debuggers to debug the
-firmware in an STM32:
+----------------------
- http://fun-tech.se/stm32/OpenOCD/gdb.php
+[This site](http://fun-tech.se/stm32/OpenOCD/gdb.php) shows several ways
+to use various debuggers to debug the firmware in an STM32.
There is a shell script called 'bin/debug' that starts an OpenOCD server
and GDB. Example:
- $ ./bin/debug projects/board-test/led-test
+ $ ./bin/debug projects/hsm/hsm
-Once in GDB, issue "monitor reset halt" to reset the STM32 before debugging.
+Once in GDB, issue `monitor reset halt` to reset the STM32 before debugging.
Remember that the first code to run will be the bootloader, but if you do
-e.g. "break main" and "continue" you will end up in led-test main() after
-the bootloader has jumped there.
+e.g. `break main` and `continue` you will end up in main() after the
+bootloader has jumped there.