{{{
#!htmlcomment
This page is maintained automatically by a script. Don't modify this page by hand,
your changes will just be overwritten the next time the script runs. Talk to your
Friendly Neighborhood Repository Maintainer if you need to change something here.
}}}
{{{
#!html
<h1>STM32 firmware for Cryptech Alpha board</h1>
<p>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 <code>hardware</code> repository for
schematics and production files. See the wiki for design documents.</p>
<p>The code in this repository builds the firmware that provides the HSM
functionality on the Alpha board.</p>
<p>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.</p>
<h1>Copyrights</h1>
<p>The license for all work done on this in the CrypTech project is a
3-clause BSD license.</p>
<p>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.</p>
<h1>Components</h1>
<h2>Libraries</h2>
<ul>
<li><p><code>mbed</code> - A stripped down copy of the ARM CMSIS library, copied from the
mbed github (see <code>libraries/mbed/README.txt</code> 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.</p></li>
<li><p><code>libhal</code> - Build directory for our own Hardware Adaption Library
(hardware-independent Cryptech components). Source is expected to be in
<code>sw/libhal</code>.</p></li>
<li><p><code>libtfm</code> - 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
<code>sw/thirdparty/libtfm</code>.</p></li>
<li><p><code>libcli</code> - Build directory for a third-party Command Line Interface
library. The source is not currently under <code>sw/thirdparty</code> because the
license is LGPLv2.1; we are negotiating to see if we can get a
BSD-compatible license for it.</p></li>
<li><p><code>libprof</code> - A port of the <code>gmon</code> 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.</p></li>
</ul>
<h2>Projects</h2>
<p>These directories build different firmware images for the Alpha board.</p>
<ul>
<li><p><code>hsm</code> - Firmware providing HSM functionality. Clients communicate via
RPC requests on the USER USB port, or interactively on the MGMT USB
port.</p></li>
<li><p><code>bootloader</code> - The first thing that runs on the device. It either starts
the primary firmware, or installs new firmware.</p></li>
<li><p><code>board-test</code> - Tests of hardware components.</p></li>
<li><p><code>cli-test</code> - Test of the CLI itself, plus some interactive tests of
hardware components. Duplicates way too much of the HSM CLI.</p></li>
<li><p><code>libhal-test</code> - A framework for running the libhal component
tests. Hasn't been run in a while, probably still works.</p></li>
</ul>
<h1>Building</h1>
<p>Our primary build environments are Debian and Ubuntu, but this should work
on any system with Gnu tools installed.</p>
<p>The following packages need to be installed:</p>
<pre><code>$ apt-get install gcc-arm-none-eabi gdb-arm-none-eabi openocd
</code></pre>
<p>The Makefile assumes that all Cryptech repositories have been fetched into
a canonical directory structure, e.g. <code>libhal</code> and <code>thirdparty</code> are
siblings to this directory, under <code>sw</code>.</p>
<p>To build the source code, issue <code>make</code> from the top level directory
(where this file is). The first time, this will build the complete STM
CMSIS library. A subsequent <code>make clean</code> will <em>not</em> clean away the CMSIS
library, but a <code>make distclean</code> will.</p>
<h1>Installing</h1>
<p>Do <code>bin/flash-target</code> 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.</p>
<p>Example loading the HSM firmware:</p>
<pre><code>$ make hsm
$ ./bin/flash-target projects/hsm/hsm
</code></pre>
<p>At this point, the STM32 will reset into the bootloader which flashes the
blue LED five times in one second, and then jumps to the primary firmware.</p>
<p>Once the bootloader is installed, regular firmware can be loaded without
an ST-LINK cable like this:</p>
<pre><code>$ cryptech_upload --firmware -i projects/hsm/hsm.bin
</code></pre>
<p>Then reboot the Alpha board.</p>
<h2>ST-LINK</h2>
<p>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
STM; we have tested with STM32F4DISCOVERY (with ST-LINK v2.0) and
NUCLEO-F411RE (with ST-LINK v2.1).</p>
<p>The ST-LINK programming pins is called J1 and is near the CrypTech logo
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</p>
<pre><code>3V3, CLK, GND, I/O, NRST and N/C
</code></pre>
<p>This matches the pin-out on the DISCO and NUCLEO boards we have tried.</p>
<p>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:</p>
<pre><code>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
</code></pre>
<p>The Alpha board should be powered on before attempting to flash it.</p>
<h2>Debugging the firmware</h2>
<p><a href="http://fun-tech.se/stm32/OpenOCD/gdb.php">This site</a> shows several ways
to use various debuggers to debug the firmware in an STM32.</p>
<p>There is a shell script called 'bin/debug' that starts an OpenOCD server
and GDB. Example:</p>
<pre><code>$ ./bin/debug projects/hsm/hsm
</code></pre>
<p>Once in GDB, issue <code>monitor reset halt</code> to reset the STM32 before debugging.</p>
<p>Remember that the first code to run will be the bootloader, but if you do
e.g. <code>break main</code> and <code>continue</code> you will end up in main() after the
bootloader has jumped there.</p>
}}}
[[RepositoryIndex(format=table,glob=sw/stm32)]]
|| Clone `https://git.cryptech.is/sw/stm32.git` ||
