Skip to content

Building a U2F Token

Jump to bottom
Conor Patrick edited this page May 21, 2018 · 41 revisions

After buying the parts, you can solder everything together like in this high res picture. Notice that the red dot on the LED should be on the left side. Two of the pins on the microcontroller have shorted traces.

Programming

You should be able to complete these instructions whether if you're on Windows, OS X, or Linux. If you're interested in programming large volumes, check out DIY Production programming instructions.

Prerequisites

  1. First you should install Simplicity Studio 3 from Silicon Labs. Simplicity Studio 4 will not work.

    • Once installed, open it and install "EFM8/C8051 8-bit Products"

  2. Install Python and pip.

  3. Install OpenSSL and USB development packages.

    # Ubuntu
sudo apt-get install openssl libssl-dev libusb-1.0-0-dev libudev-dev python-dev
# Or use OS X equivalent or Cygwin on windows

  4. Download project and python modules.

    git clone https://github.com/conorpp/u2f-zero.git
cd u2f-zero/tools/u2f_zero_client
sudo pip install -r requirements.txt --upgrade

  5. If you're on Linux, some HID devices are only accessible to root. So you will need to add a udev rule for U2F Zero.

Configuring

Using a programmer

If you are using a programmer, connect GND, C2D, and C2CK signals to your debugger/programmer device. Use this for reference. You also need to plug the U2F token into a USB port on your computer.

You will erase and program by using the flash programming utility in Simplicity Studio. Open up Simplicity Studio. On the left, click "Refresh detected hardware." The debugger you are using should show up. Under the debugger, it should detect "EFM8UB11F16G-QSOP24." If this doesn't happen, make sure you soldered it correctly. If the debugger is clearly having issues, try resetting it using Silicon Lab's reset utility.

Once detected, click on "Flash Programmer" and erase the device.

Using the USB HID bootloader

Right now I only have instructions for Windows. There is a python program that will do the loading on any platform. I haven't found a program for converting a hex file to a boot record file needed for loading. If someone finds or writes something, please let me know.

In order for firmware to be able to fit with a bootloader, you must remove some of the extra functionality. Open app.h in firmware/inc and make sure this definitions are commented out. If you don't do this, you will brick it and will need a programmer.

// Comment these out to fit firmware with a bootloader.
//#define U2F_SUPPORT_WINK
//#define U2F_SUPPORT_HID_LOCK
//#define U2F_SUPPORT_RNG_CUSTOM
//#define U2F_SUPPORT_SEED_CUSTOM

Download the bootloader utilities from Silicon Labs and go to Tools/Windows.

To load a program, run these two commands.

# convert firmware hex file to boot record
hex2boot.exe name.hex -o name.boot

# load the boot record (device must be plugged in and in bootloader mode).
efm8load.exe name.boot

Building / programming.

First we need to configure the U2F token with a set up build. This is to permanently configure the ATECC508 secure element, generate unique device secrets, and upload a device attestation key pair.

  1. With programmer or USB HID bootloader, flash the device with firmware/SETUP.hex.

    1.a Optional: If you would like to build firmware/SETUP.hex yourself, just uncomment ATECC_SETUP_DEVICE in app.h, then rebuild and firmware/release/u2f-firmware.hex will be a new setup build.

  2. Now open a terminal. We will run a set of small scripts to generate device secrets and upload a attestation key pair on the U2F token. The attestation private key and generated master key are each stored on the ATECC508 and are write only in hardware.

    # Now we can generate a key pair for U2F device attestation.
# If you have a different prime256v1 ECC key pair that you would like to use, skip this step.
# You only need to do this once.
cd ca/
./genca.sh

# The generated certificate is self-signed and can be used for attestation.  If you have a different
# signing key you would like to use to make the attestation cert, you can run this script 
# (OPTIONAL, only do this if you know what you're doing)
./ca_sign <attestation-private-key> <root-certificate> <root-private-key> <output-name>

# Now to lock ATECC508 configuration, generate device secrets, and upload the private key.
# This should be done for every token.
cd ../..
./setup_device.sh gencert/ca/key.pem gencert/ca/cert.der   # or path to your preferred attestation key pair

    The script stored some secrets and the public key in the source code file cert.c. We can build the project and program the U2F Token.

    • Open Simplicity Studio and open Simplicity IDE
    • Click File -> Import
    • General -> Existing Projects into Workspace
    • Select root directory and choose the firmware/ directory
    • Finish
    • Build project and then program U2F Token using programmer or USB HID bootloader. The firmware will be firmware/release/u2f-firmware.hex

If the LED is pulsing a green light then it is working. Double check that register and authenticate work at U2F Demo. If register signature fails, it's probably because your attestation key pair is incorrect.

  1. If you used a programmer, you are done. If you are using the USB HID bootloader and you made a mistake, you can put the token back into bootloader mode by running the following.

    ./u2f_zero_client/client.py bootloader

    Once your token is working, you should permanently disable the bootloader. You can do that by running the following.

    ./u2f_zero_client/client.py bootloader-destroy

# Double check that bootloader mode doesn't come on
./u2f_zero_client/client.py bootloader

Trouble shooting

Clone this wiki locally