Awesome

Introduction

The Armory Drive provides a pocket encrypted drive solution based on the USB armory Mk II.

It allows one-tap unlock of a microSD backed encrypted USB drive through a companion mobile application.

The USB armory firmware is a TamaGo based unikernel which allows encrypted USB Mass Storage interfacing for any plugged in microSD card.

The encrypted storage setup and authentication is meant to be performed with the F-Secure Armory Drive iOS app over Bluetooth (BLE).

To understand the firmware capabilities and use see this Tutorial.

Security Model

See the detailed specifications for full explanation of the security model.

Installation of pre-compiled releases

Binary releases are available for the Armory Drive firmware.

The binary release includes the armory-drive-install tool (for Linux, Windows and macOS) to guide through initial installation of such releases and Secure Boot activation.

[!WARNING] :lock: loading signed releases triggers secure boot activation which is an irreversible operation to be performed at your own risk, carefully read and understand the following instructions.

The installer supports the following installation modes:

F-Secure signed releases: the installation of such firmware images causes F-Secure own secure boot public keys to be permanently fused on the target USB armory, fully converting the device to exclusive use with Armory Drive releases signed by F-Secure.

These releases also enable authenticated updates through tamper-evident logs powered by Google transparency framework.
User signed releases: the installation of such firmware images causes user own secure boot keys to be created and permanently fused on the target USB armory, fully converting the device to exclusive use with user signed binaries.
Unsigned releases: such firmware images do not leverage on Secure Boot and can be installed on standard USB armory devices.

Such releases however cannot guarantee device security as hardware bound key material will use default test keys, lacking protection for stored armory communication keys and leaving data encryption key freshness only to the mobile application.

Unsigned releases are recommended only for test/evaluation purposes and are not recommended for protection of sensitive data where device tampering is a risk.

The armory-drive-install provides interactive installation for all modes and is the recommended way to use the Armory Drive firmware.

Expert users can compile and sign their own releases with the information included in section Installation of self-compiled releases.

Documentation

The main documentation can be found on the project wiki.

Operation

Pairing and initialization

See the Tutorial.

Disk access

When running with a microSD card inserted, the USB armory Mk II can be used like any standard USB drive when unlocked through its paired companion iOS app.

LED	on	off	blinking
blue	BLE active	BLE inactive	pairing in progress
white	SD card unlocked	SD card locked	firmware update in progress

Firmware update

The armory-drive-install provides interactive upgrade of all installation modes and is the recommended way to upgrade the Armory Drive firmware.

Alternatively only users of F-Secure signed releases or unsigned releases can use the following procedure on USB armory devices which have been already initialized with the Armory Drive firmware as shown in Pairing and initialization.

Download file update.zip from the latest binary release
If the USB armory contains an SD card, remove it.
Plug the USB armory.
An "F-Secure" disk volume should appear.
Copy update.zip to the "F-Secure" disk.
Eject the "F-Secure" disk.
The white LED blinks during the update and turns off on success, a solid blue LED indicates an error.
Put the SD card back in.

Installation of self-compiled releases

[!WARNING] These instructions are for expert users only, it is recommended to use armory-drive-install if you don't know what you are doing.

Compiling

Ensure that make, a recent version of go and protoc are installed.

Install, or update, the following dependency (ensure that the GOPATH variable is set accordingly):

go get -u google.golang.org/protobuf/cmd/protoc-gen-go

Build the TamaGo compiler (or use the latest binary release):

wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip
unzip latest.zip
cd tamago-go-latest/src && ./all.bash
cd ../bin && export TAMAGO=`pwd`/go

The firmware is meant to be executed on secure booted systems, therefore secure boot keys should be created and passed with the HAB_KEYS environment variable.

Build the armory-drive-signed.imx application executable:

make DISABLE_FR_AUTH=1 HAB_KEYS=<path> imx_signed

An unsigned test/development binary can be compiled with the imx target.

Installing

To permanently install armory-drive-signed.imx on internal non-volatile memory, follow these instructions for internal eMMC flashing.

[!WARNING] Once loaded, even through Serial Download Protocol, the firmware initializes its configuration by writing on the internal eMMC, therefore corrupting its previous contents.

Support

If you require support, please email us at usbarmory@withsecure.com.

Authors

Andrea Barisani
andrea.barisani@withsecure.com | andrea@inversepath.com

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation under version 3 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See accompanying LICENSE file for full details.