Ledger OS features

Introduction

This page explains several features built into Ledger OS. These features are available through the dashboard app, userspace applications, or both.

Management of cryptographic secrets

Ledger OS stores and manages two important cryptographic secrets:

• The Device keypair, which is generated in the factory
• The BIP 32 master node, which is derived from the user’s BIP 39 mnemonic seed

For security, applications cannot access either secret directly. Applications can use the Device keypair indirectly for application attestation. They can also use a Ledger OS system call to derive secrets from the BIP 32 master node, provided they received the required permissions when loaded onto the device.

Passphrases in Ledger OS

Since firmware version 1.3, Ledger OS has allowed users to load multiple BIP 39 passphrases  onto the device at once. As described in the previous chapter, a passphrase adds entropy to the BIP 39 master seed and completely changes the HD tree. Users can set a temporary passphrase that remains active until the device disconnects. They can also store a passphrase on the device by attaching it to a PIN. In that case, the passphrase activates only when the user unlocks the device with the corresponding PIN. For more information, see the Help Center article on the advanced passphrase options .

Activating a passphrase changes the binary seed derived according to BIP 39 and, therefore, the entire HD tree. Applications that derive information from the HD tree, such as cryptocurrency wallet applications, then derive different information. For example, they generate different cryptocurrency addresses.

Attestation

Attestation allows Ledger devices to prove that they are genuine. Ledger OS can use attestation when connecting to a host computer to prove that the device has not been tampered with. Applications can also use it to prove that they are running on a genuine Ledger device. For attestation purposes, Ledger OS supports device endorsement by third parties called Owners.

Anti-tampering with attestation

Anti-tampering technology built into the firmware protects Ledger devices from interdiction attacks, in which someone tampers with a device while it travels from a Ledger warehouse to a user. Attestation verifies the device’s authenticity in software whenever you connect it to a Ledger Wallet application.

During factory provisioning, each Ledger device generates a unique Device public-private keypair. Ledger’s Issuer key then signs the Device public key to create an Issuer Certificate, which is stored on the device. This certificate acts as a digital seal of authenticity. By providing its Device public key and Issuer Certificate, the device can prove that it is genuine.

When a Ledger device connects to a Ledger Wallet application, it uses the Issuer Certificate to prove its authenticity. This process occurs while establishing the Secure Channel, described later on this page. If an attacker created a clone that ran rogue firmware, attestation would fail, and the application would reject the device as non-genuine. An attacker cannot replace the device firmware and pass attestation without a Device private key and the corresponding Issuer Certificate signed by Ledger.

Compromising the Device private key is extremely unlikely because the Secure Element is designed to resist physical attacks. Extracting the private key is theoretically possible, but it requires extensive time and resources.

Endorsement & application attestation

As described in the previous section, the Device private key can prove that a Ledger device is genuine. To prevent compromising this key, only Ledger OS can access it directly. Applications can use the Device private key indirectly for attestation by generating attestation keypairs.

Users can generate attestation keypairs on demand for applications. They can set up an attestation key with endorsementSetup.py or endorsementSetupLedger.py. During generation, the host computer connects to the Dashboard application and initiates a Secure Channel. It then instructs the device to create an attestation keypair.

The device generates a new attestation keypair and signs it with the Device private key to create a Device Certificate. It returns the attestation public key, Device Certificate, and Issuer Certificate to the host over the Secure Channel. The host, which may be Ledger or a third party, signs the attestation public key with an Owner private key. This signature creates an Owner Certificate, which the host sends back over the Secure Channel for storage on the device. In this way, the Owner endorses the device’s authenticity.

The device can then use the Device Certificate and Issuer Certificate to prove that the attestation key belongs to a genuine Ledger device. It can use the Owner Certificate to prove that the Owner trusts the attestation key.

Applications cannot access attestation keys directly. Instead, Ledger OS gives userspace applications attestation functionality through cryptographic primitives available as system calls. Applications can use two Endorsement Schemes: Endorsement Scheme #1 and Endorsement Scheme #2. When creating an attestation keypair, the user chooses its scheme. Applications use the keypair through the cryptographic primitives available for that scheme.

Endorsement Scheme #1 offers two cryptographic primitives:

• os_endorsement_key1_get_app_secret(...) derives a secret from the attestation private key and the hash of the running application.

• os_endorsement_key1_sign_data(...) signs a message concatenated with the hash of the running application using the attestation private key. The signature can be verified with verifyEndorsement1.py.

Endorsement Scheme #2 offers a single cryptographic primitive:

• os_endorsement_key2_derive_sign_data(...) signs a message using a private key derived from the attestation private key and the hash of the running application. The signature can be verified with verifyEndorsement2.py.

For an example of these features, see blue-app-otherdime  and this blog post , which discusses the application in detail.

Attestation chain of trust

The chain of trust for Ledger’s attestation model

The diagram shows the chain of trust in the attestation model. The Device Certificate proves that the attestation keys belong to a device, and the Issuer Certificate proves that the device is genuine. Together, these certificates establish that a genuine Ledger device signed the data. The Owner Certificate proves that an Owner, which may be Ledger or a third party, trusts the attestation keys.

Secure Channel

A host computer can establish a Secure Channel with a device during its standard lifecycle. This channel lets the host verify the device’s authenticity and exchange secrets with it securely.

As described in the anti-tampering section, a host computer can verify a Ledger device by requesting its Issuer Certificate, which Ledger signs. This verification occurs when the host establishes a Secure Channel with the device. The Secure Channel also provides encrypted communication between the host and device. Only the dashboard application can establish this channel because the process requires access to the Device private key.

The Secure Channel protocol builds on the APDU (Application Protocol Data Unit) protocol used to communicate with the device over USB. The host computer sends a series of Command APDUs, and the device returns a corresponding Response APDU for each command.

The Secure Channel connects two parties: the Signer and the Device. Here, the Signer is the remote host that connects to the device. The Signer may be the Issuer (Ledger) connecting through Ledger APIs, a Custom Certificate Authority connecting with a previously enrolled Custom CA public key, or another end user using a randomly generated keypair.

To establish the Secure Channel, the Signer and Device each generate an ephemeral keypair. They use these keypairs to calculate a shared secret through ECDH for encrypted communication. Each party provides a certificate chain to prove that it trusts its ephemeral public key. The certificate chains include both a Signer nonce and a Device nonce to prevent an eavesdropper from reusing the certificates.

If a party trusted by the device signed the root certificate in the Signer’s certificate chain, the device gives the remote host special permissions after establishing the Secure Channel. For example, the host can add or remove applications without user confirmation if a previously enrolled Custom CA keypair or Ledger’s Issuer keypair signed the root certificate.

The following diagram illustrates how the parties establish a Secure Channel.

The Secure Channel protocol handshake

In segment (6) of the diagram, the Device provides a Signer serial. This number is stored by the device and identifies the Issuer keypair used to sign the device’s Issuer Certificate. Ledger does not use the same Issuer keypair for every device.

From segments (7) to (11), the Signer certificate chain is generated, sent to the device, and verified. From segments (12) to (16), the Device certificate chain is generated, sent to the Signer, and verified. In this example, each chain contains two certificates.

The root certificate in the Signer certificate chain is self-signed. The Signer signs the final certificate, which verifies the Signer’s ephemeral public key. In the Device certificate chain, the Issuer Certificate is the root certificate. Verifying it also verifies the device’s authenticity. The Device signs the final certificate, which verifies the Device’s ephemeral public key.

Custom CA public key enrollment

A Custom Certificate Authority can generate a keypair with genCAPair.py and enroll its public key on the device with setupCustomCA.py. Enrollment gives the Custom CA two special privileges:

• The Custom CA can open an authenticated Secure Channel with the device by using the --rootPrivateKey option of the Python Loader.
• The Custom CA can sign applications with signApp.py. This signature allows the device to load the application without user confirmation.

Ledger OS application developers can use this feature to simplify development. Third-party companies can also use it to give their own application manager permission to manage the device without requiring user confirmation for every action.

Parties involved in the model

The following parties participate in the public key cryptography model.

Device

Device Certificate: Each Device has a unique public-private keypair known only to that device. The Device generates this keypair in the factory, and Ledger does not know its private key. The Device keypair can sign certificates.

Issuer

Issuer Certificate: The Issuer is the party that initially provisions the Device. This party is always Ledger. The Issuer has a public-private keypair that can sign Issuer Certificates. Ledger uses multiple Issuer keypairs.

Owner

Owner Certificate: An Owner is a party that owns a Ledger device, verifies its authenticity, or both. An Owner has a public-private keypair that can sign certificates. A single Device can have zero or more Owners, and an Owner does not have to be Ledger. The device uses Owner Certificates only for application attestation.

Custom CA

Custom CA Certificate: A Custom Certificate Authority has a public-private keypair. Its public key is enrolled on the device, and its private key can establish an authenticated Secure Channel with the device and sign applications.