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:

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.
Copy
Copied
#!/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()
Make sure you
  • Respect the curve, encoding, and serializations for the keys to be valid.
  • Name your files as mentioned above to allow LAM to find your keys.
  1. 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.
  2. Make sure the certificate folders are structured as follows:
Copy
Copied
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.

Copy
Copied
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.

Copy
Copied
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:

Copy
Copied
{"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>
Copyright © Ledger Enterprise Platform 2022. All right reserved.