Edgars Nemse

Building on the Ledger Nano S

February 14, 2018

At Radix we’re developing the next generation distributed ledger technology. We want to provide people with secure ways to store their Radix coins, and there's nothing quite as secure as using a hardware wallet, also known as a cold wallet.

In this post I'll describe what cold wallets are exactly and how they work, as well as go into detail about how to set up the build environment for the Ledger Nano S, compile a Hello World application and deploy it to the Nano S. I decided to write this as I ran into some trouble with the official guide provided by Ledger.

What is a cold wallet?

A cold wallet is a method of storing private keys that isn't connected to the internet. This prevents attackers, no matter how clever, from stealing your private keys unless they gain physical access to the cold wallet device.

The simplest way of going about this is writing down your private keys on a piece of paper. This approach has some obvious drawbacks, such as that anyone who can take a picture of that piece of paper has access to your wallet, as well as some more subtle problems - whenever you want to make a transfer, you will need to input the key into an internet connected device, at which point you’re open to all of the same attack vectors as if you had just stored the key on the computer the whole time.

There is a way around the problem - you could have a USB device that stores your private keys. When you want to make a transaction, you connect it to your computer, create the transaction and send it to your hardware wallet to sign with your private key. The wallet then returns a signed transaction. But your private keys have never left the wallet. So even if an attacker has fully compromised your computer, your private keys are safe. They aren't bulletproof however it’s about as secure as you can get nowadays.

The three main companies that make this type of hardware wallet are Ledger, Trezor and KeepKey. We chose Ledger Nano S to start with.

How it works

When you first start up a Nano Ledger S an interesting thing happens - you are asked to note down a list of random 24 words. This mnemonic is your master key. It maps to a 256 bit long number but it's a lot easier to note down and potentially remember a 24 word mnemonic than a list of 256 ones and zeroes.

Your master key is one of $$2^{256}$$ possible keys. That is one of 115 792 089 237 316 195 423 570 985 008 687 907 853 269 984 665 640 564 039 457 584 007 913 129 639 936 possible mnemonic seeds. For comparison, there are an estimated $$2^{223}$$ atoms in the Milky Way. Somebody getting the same key as you is orders of magnitude less likely than somebody randomly picking an atom in your left toe from all the atoms in the galaxy.

The Ledger S uses what is known as Hierachical Deterministic Key Generation. This means that it can derive a virtually infinite number of private-public key pairs from a single starting point - the master key. And because the process is deterministic, it will yield the same keys even when you import the same master key on a new Nano S, or even any other hardware or software wallet that implements the same key generation scheme.

To avoid clashes between different applications, the developers of different cryptocurrencies have gotten together and reserved a space on the tree for each coin.Bitcoin lives at index 0, index 1 is reserved for testnets of all coins, 2 is Litecoin and interestingly Dogecoin is at index 3. You can see the full list here

All of this means that you have a virtually infinite number of private/public key pairs for any cryptocurrency you want to hold in the wallet, all derived from the single master key.

How to get started developing for the Ledger Nano S

I ran into some difficulties setting up the build environment for Ledger hardware wallets following the guides provided by Ledger, so I have compiled my own guide with steps that worked for me. I use OS X, but this guide should work on any operating system, since we’re using Docker.

Things you will need to get started

These are the tools required for building and deploying applications for the Nano S. Follow the respective installation guides for your operating system:

Setting up the build environment

The easiest way to get started with making your own custom apps for the Nano S is using Docker.In this guide we will build and deploy the blue-app-helloworld found at https://github.com/LedgerHQ/blue-sample-apps/tree/master/blue-app-helloworld. Clone the repository wherever you would like, I have mine under /Users/edgarsnemse/Documents/Dev/blue-sample-apps

The first step is to pull the Docker image we will be using to build the application.

docker pull nbasim/ledger-blue-sdk

Afterwards you can run the docker image. We need to make the source directory accessible within the docker container. This can be achieved using the --mount flag. It can take a number of arguments, all of which can be seen here, but in our case we only care about 3 of them - type=bind, source=[path on the host OS] and target=[path inside the container].

docker run -t -i --mount type=bind,source=/Users/edgarsnemse/Documents/Dev/blue-sample-apps,target=/home/dev nbasim/ledger-blue-sdk /bin/bashapt-get updateapt-get install libc6-dev-i386cd/home/dev/blue-sample-apps/blue-app-helloworldmake BOLOS_ENV=/opt/ledger-blue/ BOLOS_SDK=/home/dev/BOLOS_SDK

This will create an app.hex file in the blue-app-helloworld/bin directory. This is the binary of your application which you can now install and run on your Nano S.

Installing the application on the device

Ledger provides a Python-based tool to install compiled binaries to their devices. It can do a lot more but for now we’re only interested in the application deployment tools.

First you need to install the pip package. It is recommend installing it in a virtualenv to avoid any dependency versioning issues.

virtualenv ledgersource ledger/bin/activatepip install ledgerblue

You can then use the following command from the bin directory containing the app.hex file to deploy your application to the Nano S.

python -m ledgerblue.loadApp --targetId 0x31100002 --apdu --fileName app.hex --appName Hello --appFlags 0x00

You should now see the Hello application listed in the  app menu on the Nano S.

Uninstalling

To remove the appliocation from the device use this command.

Conclusion and next steps

At this point you are ready to start developing your applications. If you want to read more about how the Nano S works, Ledger provide a very detailed document here. If you are considering developing your own applications for Ledger hardware wallets, you can find the full documentation here.