Overview of the Ledger Vault's API

The Ledger Authentication Module (LAM) is your internal gateway to the Ledger Vault's API. It exposes a simple, easy-to-use, and secure REST API for the Ledger Vault.

Running the Ledger Authentication Module (LAM)

LAM runs as a standalone Docker image. The following diagram describes how LAM communicates with the Ledger Vault.

This design is similar to what you do when you are using a Ledger Hardware Device to connect to the Ledger Vault platform. You can think of the following analogy: Front + Hardware Device <=> Http Client + LAM

We use hardware secure elements to keep your secrets safe in the Ledger network when you are using LAM. However, some sensitive information lies in your own network.

Because it’s hard to ensure the same level of security on standard machines than it is on dedicated secure elements, special care must be taken to secure the machine running LAM.

The authentication between LAM and the Ledger Vault is a transparent process that is entirely handled by LAM.

Ledger will provide you a signed certificate following your Certificate Signing Request (CSR) that will be used to trust your messages to the Vault.

Hence, the only link needed to access the Vault is between this Docker running container and – in demo mode – the machine pointed by the domain https://api.vault.cit.ledger-test.com.

Data Flow Summary

The following diagram summarizes the interactions you could have with LAM. It highlights the data flows in the current state of LAM.

Set up the User Seed and Certificate Storage volumes carefully as they contain sensitive information, especially in the production stage. If necessary, we can assist you during this process.

Security

The primary reason for accessing the Vault using a Ledger certified hardware (i.e. the Ledger Blue) is that we have been able to assess with reasonable certainty that your secret is secure in this framework.

The purpose of LAM is to act as a certified device, although it isn’t a Ledger validated Hardware device, nor does it run on hardware that is certified by Ledger.

The only channel on which we have full control is the communication between LAM and the Vault.

The sensitive information required by LAM to communicate with the Vault is held by you. It is accessible to LAM through shared volumes and is composed of your LAM certificate and your API users seeds.

Certificate

The LAM certificate, issued by Ledger, is used to initialize the secure channel between LAM and the Vault HSM. If you use multiple environments, a unique certificate will be issued for each.

API users’ seeds

The seeds are generated on demand by LAM. They’re made of 24 words, which means they are 256 bits BIP39 seed phrases. For more details on seed phrases, see the Bitcoin wiki.