Get started with the Ledger Vault's API

The Ledger Authentication Module (LAM) is your internal gateway to the Ledger Vault's API.

Prerequisites

Your environment must contain the following applications:

• Docker
• Python 3.8
• Python cryptography

Step by step guide

Step 1. Generate your private and public key pair

1. Use the following Python example to generate your private and public key pair. This is a an important step that you must perform carefully.

#!/usr/bin/env python3

from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec


def main():
    private_key: ec.EllipticCurvePrivateKey = ec.generate_private_key(
        curve=ec.SECP256K1(), backend=default_backend()
    )
    private_bytes = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
    format=serialization.PrivateFormat.TraditionalOpenSSL,
        encryption_algorithm=serialization.NoEncryption(),
    )
    with open("lam_private.pem", "wb") as f:
        f.write(private_bytes)
    print("Created new file lam_private.pem")

    public_key: ec.EllipticCurvePublicKey = private_key.public_key()
    public_bytes = public_key.public_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PublicFormat.SubjectPublicKeyInfo,
    )
    with open("lam_public.pem", "wb") as f:
        f.write(public_bytes)
    print("Created new file lam_public.pem")


if __name__ == "__main__":
    main()

2. Send your public key to you Account manager so we generate your LAM certificate. We’ll then sign it to ensure LAM can communicate securely with our services.
3. Make sure the certificate folders are structured as follows:

ls -l cert_storage/
total 12K
-rw-r--r-- 1 ledger 136 May 15 10:16 lam.certificate
-rw-r--r-- 1 ledger 223 May 15 10:14 lam_private.pem
-rw-r--r-- 1 ledger 174 May 15 10:14 lam_public.pem

Step 2. Create the user's secrets storage

LAM generates the user’s secrets at runtime. To store them persistently, you have to set up an external docker volume (user_storage) that won’t be destroyed if the container stops.

mkdir user_storage

See API users, for more information on how to create users.

Step 3. Ledger Authentication Module as a Docker container

The LAM image is published on our Docker Registry. We will provide you with the Docker login credentials required to access it.

• Use your Docker login credentials to login to 7930t6gv.gra7.container-registry.ovh.net
• Pull the latest LAM image version from our Docker registry at 7930t6gv.gra7.container-registry.ovh.net/vault lam distribution/vault-lam:1.8.0
• Run the Docker image on your infrastructure, specifying the environment variables:
  • The workspace name provided by our Onboarding team
  • The API gateway base URL provided by our Onboarding team
  • The path to your LAM certificate storage and user storage (see Step 2)

Below is an example of a Docker invocation to run version 1.8.0 of LAM, on the <host_port> port of the host machine.

docker run -p <host_port>:5000 -d --rm \
-v <cert_dir_on_host>:/cert_storage \
-v <cert_dir_on_host>:/user_storage \
-e WORKSPACE=<name_of_your_workspace> \
-e API_GATEWAY_BASE_URL=https://api.vault.ledger.com \
-e CERT_STORAGE_PATH=/cert_storage \
-e USER_STORAGE_PATH=/user_storage \
7930t6gv.gra7.container-registry.ovh.net/vault_lam_distribution/vault-lam:1.8.0

Step 4. Check connectivity

You can test LAM is connected to the Vault via: curl -v http://localhost:<host_port>/_health

The output should look like:

{"api_gateway":{"<workspace>":{"success":true},"success":true},"success":true}"

Step 5. (Optional) Set up an API key

For additional security, you can set up an API Key that all users of the API will need to provide.

1. Generate a random string. Here is an example using Python.
2. In the docker run command mentioned in step 3 above, add -e API_AUTHENTICATION_KEY=<secret_string>
3. Make sure all API calls contain the header: X-Ledger-API-Key: <secret_string>