Introduction

lib_pki is a thin wrapper around the OS PKI layer (os_pki_get_info / os_pki_verify). It provides a single function, check_signature_with_pki(), that verifies a signature against a Ledger-issued PKI certificate previously loaded into the device by the OS.

It is intended for use cases where Ledger's back-end authenticates data sent to an application — for example, verifying a trusted-name descriptor or a transaction risk assessment before displaying it to the user.

Usage

Prerequisites

Before calling check_signature_with_pki(), the OS must have already loaded the relevant PKI certificate (this is handled transparently by the OS when the host sends an APDU that embeds a certificate chain).

Verifying a signature

#include "ledger_pki.h"
 
// key_usage and curve are optional filters; pass NULL to skip the check.
static const uint8_t  EXPECTED_KEY_USAGE = CERTIFICATE_KEY_USAGE_TRUSTED_NAME;
static const cx_curve_t EXPECTED_CURVE   = CX_CURVE_256K1;
 
check_signature_with_pki_status_t status =
    check_signature_with_pki(hash_buf,
                             &EXPECTED_KEY_USAGE,
                             &EXPECTED_CURVE,
                             signature_buf);
 
if (status != CHECK_SIGNATURE_WITH_PKI_SUCCESS) {
    // Reject the data — do not display it to the user
    return false;
}

Return codes

Status	Meaning
CHECK_SIGNATURE_WITH_PKI_SUCCESS	Signature is valid
CHECK_SIGNATURE_WITH_PKI_MISSING_CERTIFICATE	No PKI certificate is currently loaded in the OS
CHECK_SIGNATURE_WITH_PKI_WRONG_CERTIFICATE_USAGE	The loaded certificate's key-usage does not match `expected_key_usage`
CHECK_SIGNATURE_WITH_PKI_WRONG_CERTIFICATE_CURVE	The loaded certificate's curve does not match `expected_curve`
CHECK_SIGNATURE_WITH_PKI_WRONG_SIGNATURE	The signature verification failed

Any non-zero status must be treated as a security failure: the signed data must not be trusted or displayed.