Skycoin hardware wallet
Table of contents
- Install tools
- Build instructions:
- Development guidelines
This repo contains the firmware and bootloader for the Skywallet as well as tools to test and develop for the Skywallet. The firmware can be found in /tiny-firmware. The firmware has been modified from Trezor.
Get the development dependencies and tools from the tiny-firware/README.md first, before continuing with the build instructions.
After cloning this repository, make sure the submodules are up-to-date by executing the following command:
git submodule update --init --recursive
Should you find any issues while running any of the commands that follow please consult FAQ before reporting a bug.
Build a bootloader
make bootloader # Your firmware is skybootloader-no-memory-protect.bin
Build a bootloader with memory protection enabled
Careful if you flash and run that bootloader on the device it will activate a memory protection that will close access to flash memory.
You won't be able to flash your device with an st-link again.
make bootloader-mem-protect # Your firmware is bootloader-memory-protected.bin
Build a firmware
make firmware # Your firmware is tiny-firmware/skyfirmware.bin
Signs the firmware with the private key corresponding to the PubKeys that were registered in the bootloader during building. The PubKeys can be found in the project Makefile
make sign # Your firmware is tiny-firmware/skyfirmware.bin
Sign on MacOS with docker
Currently, the firmware cannot be signed on MacOS straight away. In order to sign the firmware on MacOS nonetheless, you can use the
sign.sh script which requires a stable Docker release to be installed.
Combine bootloader and firmware
This creates a combined firmware without memory protection.
make full-firmware # this will create a full-firmware-no-mem-protect.bin file
Combine a memory protected bootloader and firmware
Caution: This combined firmware has memory protection enabled and therefore cannot be re-flashed.
make full-firmware-mem-protect # this will create a full-firmware-memory-protected.bin file
Build and run emulator
make clean && make run-emulator
In case of needing special compiler flags for the SDL library it is possible to provide them in
SDL_CFLAGS variable. For instance , if SDL was installed with brew on Mac OS X then the following command execution would force searching for header files at the right location.
make clean && make run-emulator SDL_CFLAGS=-I$(brew --prefix sdl2)/include/SDL2
However for the default
brew installation in practice this should not be needed since the value of
SDL_CFLAGS defaults to
$(shell sdl2-config --cflags | sed 's/-D_THREAD_SAFE//g').
Code added in this repository should comply with the development guidelines documented in the Skycoin wiki.
This project has two branches:
developis the default branch and will always have the latest code.
masterwill always be equal to the current stable release on the website, and should correspond with the latest release tag.
Firmware version scheme
The firmware follows Semver.
The firmware binary filename is
Bootloader version scheme
The bootloder versioning is independent of the firmware versioning, but follows Semver as well.
The bootloader binary filename is
skywallet-bootloader-mem-protect-v$(VERSION_BOOTLOADER).bin if compiled with memory protection enabled it is
skywallet-bootloader-no-memory-protect-v$(VERSION_BOOTLOADER).bin. For instance,
skywallet-bootloader-no-memory-protect-v1.0.2.bin could be bootloader file names.
In order to identify at first sight the features supported by a particular release of a client library, its major and minor version numbers should match the corresponding values of the version of the firmware they were built (tested) for. It is expected that the aforementioned library will be able to communicate to any firmware, as long as both versions (client and firmware) have the same major version number and firmware minor number is greater than the one of the library.
The project includes a test suite. In order to run it just execute the following command
make clean && make test
Generating tests code coverage
To generate code coverage html report you need to have
lcov available in your
PATH, in a debian based system you can run
apt install lcov, lcov can be available using
brew on osx too, but in the most general case you can follow the the official install instructions.
After having this tool you can run
make check-coverage, if not errors found you can find the result in
Skycoin firmware releases
Upon startup, the bootloader checks the validity of the firmware installed on the device. It checks whether the signatures of the firmware correspon to the PubKeys registered in the bootlaoder. The firmware is expected to have a header with proper MAGIC number and three signature slots.
If the firmware does not have a valid signature in its header it is considered "not official". A warning will be displayed but the user can still skip it and use it anyway.
Update the version
- If the
masterbranch has commits that are not in
develop(e.g. due to a hotfix applied to
develop(and fix any build or test failures)
- Switch to a new release branch named
release-X.Y.Zfor preparing the release.
tiny-firmware/bootloader/VERSIONwith corresponding version numbers
make buildto make sure that the code base is up to date
CHANGELOG.md: move the "unreleased" changes to the version and add the date.
- Follow the steps in pre-release testing
- Make a PR merging the release branch into
- Ensure changes needed in protobuffer specs are merged into its
- Ensure protobuf specs sub-module will track changes from its
masterbranch after merge
- Review the PR and merge it
- Tag the
masterbranch with the version number. Version tags start with
v0.20.0. Sign the tag. If you have your GPG key in github, creating a release on the Github website will automatically tag the release. It can be tagged from the command line with
git tag -as v0.20.0 $COMMIT_ID, but Github will not recognize it as a "release".
- Tag the changeset of the
protobsubmodule checkout with the same version number as above.
- Release builds are created and uploaded by travis. To do it manually, checkout the master branch and follow the create release builds instructions.
developbranch and bump
Once the candidate release build artifacts have been downloaded it is necessary to check once again that they behave according to specifications. The followinfg steps are aimed at ensuring this is the case. Execute
- Flash the device with latest versions of bootloader and firmware
- Ensure you have a recent version of Skycoin desktop software in one of the following ways
- build desktop wallet from source either following instructions from master branch or from develop branch
- download Skycoin wallet from official downloads page
- Open desktop wallet
- Recover a test wallet with nonzero balance from seed to confirm wallet loading works
- Send coins to another wallet to confirm spending works
- Check that transferred amounts reported in transaction history are correct
- Add a PIN to the hardware wallet
- Use the same recovery seed of the wallet configured in the Skywallet device and to load a wallet directly in desktop wallet
- Send coins to another wallet again
- Check transaction history once again
- Wipe the wallet
- Set up the hardware wallet with a random seed and write down the first address
- Create a seed backup
- Wipe the wallet and restore the seed. Check if the first address is equal to the one previously written
- Repeat steps from the top but using combined bootloader + firmware image to flash the hardware wallet device.
Creating release builds
The following instruction creates a full release:
Firmware version will be retrieved automatically from
git, and bootloader version will be take from
Security flaws in Skywallet source code or infrastructure can be sent to firstname.lastname@example.org. Bounties are available for accepted critical bug reports.
PGP Key for signing:
-----BEGIN PGP PUBLIC KEY BLOCK----- mDMEXYCYPxYJKwYBBAHaRw8BAQdAeDPi3n9xLv5xGsxbcbwZjfV4h772W+GPZ3Mz RS17STm0L2lrZXRoZWFkb3JlIHNreWNvaW4gPGx1eGFpcmxha2VAcHJvdG9ubWFp bC5jb20+iJYEExYIAD4WIQSY+TTwT5M0uB36M5iRO71SBrGWIAUCXYCYPwIbAwUJ B4TOAAULCQgHAgYVCgkICwIEFgIDAQIeAQIXgAAKCRCRO71SBrGWID0NAP0VRiNA 2Kq2uakPMqV29HY39DVhc9QgxJfMIwXWtFxKAwEAn0NqGRV/iKXNf+qxqAtMWa5X F2S36hkEfDHO5W44DwC4OARdgJg/EgorBgEEAZdVAQUBAQdAeiEz/tUmCgOA67Rq ANmHmX2vrdZp/SfJ9KOI2ANCCm8DAQgHiH4EGBYIACYWIQSY+TTwT5M0uB36M5iR O71SBrGWIAUCXYCYPwIbDAUJB4TOAAAKCRCRO71SBrGWIJOJAQDTaqxpcLtAw5kH Hp2jWvUnLudIONeqeUTCmkLJhcNv1wD+PFJZWMKD1btIG4pkXRW9YoA7M7t5by5O x5I+LywZNww= =p6Gq -----END PGP PUBLIC KEY BLOCK-----
Key ID: 0x913BBD5206B19620
The fingerprint for this key is:
pub ed25519 2019-09-17 [SC] [expires: 2023-09-16] 98F934F04F9334B81DFA3398913BBD5206B19620 uid [ultimate] iketheadore skycoin <email@example.com> sub cv25519 2019-09-17 [E] [expires: 2023-09-16]
Keybase.io account: https://keybase.io/iketheadore