Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
Address Book API

Introduction

The Address Book feature allows a Ledger device to securely associate human-readable names with blockchain identifiers or Ledger-managed accounts. The device is stateless: nothing is stored persistently. On registration the device generates a random group_id (gid, 32 bytes), authenticates it as a group_handle (64 bytes), and returns two independent HMAC Proofs of Registration that the wallet stores alongside the contact record.

Because the device is stateless, proofs cannot be revoked: after any confirmed edit (contact name, identifier, scope, or Ledger Account name), the previous proofs remain valid and the device still accepts them, including in the Provide Contact commands, which have no review screen. The wallet (Ledger Wallet) must therefore delete the previous proofs as soon as the new ones are stored.

The feature provides:

  • Binding a contact name and scope to an external identifier (e.g. an Ethereum address) via the Register Identity flow
  • Linking multiple addresses to a single contact by re-calling Register Identity with an existing group_handle — all addresses then share the same name and rename atomically
  • Binding an account name to a BIP32 derivation path managed by the device via the Register Ledger Account flow
  • Updating existing bindings (name, identifier, scope) via dedicated Edit flows — each verified by presenting the stored group_handle and the relevant HMAC proof(s)
  • Cryptographic resistance to proof splicing: the wallet cannot mix HMAC proofs from different contacts because the device generates and authenticates gid itself
  • No plaintext secrets leave the device: the host receives only the HMAC proofs

Architecture

The Address Book implementation is split between the SDK and coin applications:

  • SDK Core: TLV parsing, group handle generation and verification, HMAC key derivation, HMAC computation and verification, Edit UI flows
  • Coin Application: identifier / account validation, blockchain-specific checks, Register Identity and Register Ledger Account UI, tag-value pairs for Edit Identifier

Sub-Commands

The Address Book APDU (CLA=0xB0, INS=0x10) dispatches on P1:

P1 Sub-command Struct type Guard
0x01 Register Identity 0x2d HAVE_ADDRESS_BOOK
0x02 Edit Contact Name 0x2e HAVE_ADDRESS_BOOK
0x03 Edit Identifier 0x31 HAVE_ADDRESS_BOOK
0x04 Edit Scope 0x32 HAVE_ADDRESS_BOOK
0x11 Register Ledger Account 0x2f HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT
0x12 Edit Ledger Account 0x30 HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT
0x20 Provide Contact 0x33 HAVE_ADDRESS_BOOK
0x21 Provide Ledger Account Contact 0x34 HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT

Command Flows

Sequence diagrams for Register Identity (P1=0x01) and Register Ledger Account (P1=0x11) are available in Mermaid format in app_features/address_book/doc/address_book_spec.md (viewable on GitHub/GitLab).

Data Structures

TLV Tags

Tag Name Description Max size
0x01 STRUCTURE_TYPE Sub-command type discriminator (0x2d–0x33) 1 B
0x02 STRUCTURE_VERSION Always 0x01 1 B
0xf0 CONTACT_NAME Human-readable contact/account name 32 B
0xf1 SCOPE Scope/namespace for the identifier 32 B
0xf3 PREVIOUS_NAME old name (Edit Contact Name only) 32 B
0xf2 ACCOUNT_IDENTIFIER Opaque identifier (e.g. 20-byte Ethereum address) 80 B
0xf4 PREVIOUS_IDENTIFIER old identifier (Edit Identifier only) 80 B
0xf5 PREVIOUS_SCOPE old scope (Edit Scope only) 32 B
0xf6 GROUP_HANDLE Device-generated token: gid(32) + HMAC-SHA256(K_group, gid)(32) 64 B
0x69 DERIVATION_PATH BIP32 path for address derivation (Ledger Account only) 43 B
0x23 CHAIN_ID Chain ID (mandatory for Ethereum family) 8 B
0x51 BLOCKCHAIN_FAMILY Blockchain family enum 1 B
0x29 HMAC_PROOF HMAC-SHA256 over gid + contact name 32 B
0xf7 HMAC_REST HMAC-SHA256 over gid + scope + identifier + network 32 B

Response Formats

// Register Identity (0x2d): 129 bytes
type(1) | group_handle(64) | hmac_proof(32) | hmac_rest(32)
// Edit Contact Name (0x2e): 33 bytes — new HMAC_PROOF
// Edit Identifier (0x31): 33 bytes — new HMAC_REST
// Edit Scope (0x32): 33 bytes — new HMAC_REST
type(1) | hmac(32)
// Register Ledger Account (0x2f): 33 bytes
// Edit Ledger Account (0x30): 33 bytes
type(1) | hmac_proof(32)
// Provide Contact (0x33): no data
// Provide Ledger Account Contact (0x34): no data
9000

Cryptographic Design

Group Handle

At registration the device generates a random 32-byte Group ID (gid) and authenticates it with a separate device key via OS syscall. The resulting opaque token has the structure:

group_handle = gid(32) || MAC(K_group, gid)(32)

The wallet stores group_handle opaquely. For each Edit operation the wallet re-sends the full group_handle; the device verifies the MAC via syscall in constant time and — only on success — extracts gid to authenticate the HMAC proofs.

This closes the proof splicing attack: a wallet that registers two contacts cannot mix HMAC_PROOF from one with HMAC_REST from the other, because neither can fabricate a valid group_handle for an arbitrary gid.

Cryptographic Operations

Group Handle generation/verification and Identity HMAC computation/verification are fully delegated to the OS via dedicated syscalls — key derivation details are internal to the OS and not exposed to the coin application.

HMAC Message Formats

Identity — HMAC_PROOF:

message = gid(32) | name_len(1) | contact_name

Identity — HMAC_REST:

message = gid(32) | scope_len(1) | scope | id_len(1) | identifier | family(1) [| chain_id(8)]

chain_id is included only when BLOCKCHAIN_FAMILY = 1 (Ethereum), encoded as 8 bytes big-endian.

Ledger Account — HMAC_PROOF:

message = name_len(1) | account_name | blockchain_family(1) [| chain_id(8)]

Key Design Decisions

  1. Device-generated gid: The device generates gid randomly rather than accepting a wallet-chosen contact ID. Combined with the authenticated group_handle, this prevents proof splicing attacks where a malicious wallet mixes proofs from different contacts.
  2. Two independent Identity HMACs: HMAC_PROOF covers only gid + name, while HMAC_REST covers gid + scope + identifier + network. This allows the wallet to rename a contact without re-presenting the identifier or scope, and vice-versa.
  3. Multi-address contacts: Register Identity can be called with an existing group_handle + HMAC_PROOF to link a second (scope, identifier) pair to the same gid. The device verifies ownership before issuing a new HMAC_REST. Because all addresses share the same gid, a single Edit Contact Name returns a new HMAC_PROOF for every address in the group simultaneously. The previous HMAC_PROOF is not revoked: the device is stateless and still accepts it, so the wallet (Ledger Wallet) must delete it once the new one is stored.
  4. Syscall-backed crypto: All cryptographic operations (Group Handle, Identity, and Ledger Account) are delegated to OS syscalls with distinct domain-separation salts, preventing cross-feature key reuse.
  5. No secrets leave the device: The BIP32 private key, KDF keys, and gid are computed on-device. The host receives only the opaque group_handle and HMAC proofs.
  6. App validation: Coin-specific validation logic is delegated to the application via callbacks, maintaining separation of concerns.
  7. User confirmation: A mandatory review screen ensures users explicitly approve each registration before the HMAC proofs are sent.

API Reference

Application Callbacks

Applications must implement the following callbacks to support Address Book:

Register Identity:

void finalize_ui_register_identity(void)
Handle called to finalize the UI flow for registering an Identity.
bool handle_check_register_identity(identity_t *params)
Handle called to validate the received Identity.
nbgl_contentTagValue_t * get_register_identity_tagValue(uint8_t pairIndex)
Callback to retrieve a tag-value pair for the Register Identity UI.
Data extracted from a Register Identity TLV payload.
Definition identity.h:62
This structure contains a [tag,value] pair and possible extensions.

Edit Identifier:

bool handle_check_edit_identifier(const edit_identifier_t *params)
Handle called to validate and store the Edit Identifier parameters.
nbgl_contentTagValue_t * get_edit_identifier_tagValue(uint8_t pairIndex)
Callback to retrieve a tag-value pair for the Edit Identifier UI.
void finalize_ui_edit_identifier(void)
Handle called to finalize the UI flow for editing an Identifier.
Data extracted from an Edit Identifier TLV payload.
Definition identity.h:75

Edit Contact Name / Edit Scope (SDK handles display):

void finalize_ui_edit_contact_name(void)
Handle called to finalize the UI flow for editing a contact name.
void finalize_ui_edit_scope(void)
Handle called to finalize the UI flow for editing a scope.

Register Ledger Account (requires HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT):

bool handle_check_register_ledger_account(ledger_account_t *params)
Handle called to validate the received Ledger Account.
void display_register_ledger_account_review(nbgl_choiceCallback_t choice_callback)
Handle called to display the Ledger Account registration review screen.
void finalize_ui_ledger_account(void)
Handle called to finalize the UI flow for a Ledger Account operation.
void(* nbgl_choiceCallback_t)(bool confirm)
prototype of choice callback function
Data extracted from a Register Ledger Account TLV payload.

Provide Contact:

bool handle_provide_identity(const identity_t *contact);
bool handle_provide_identity(const identity_t *contact)
Handle called to store a verified contact.

Provide Ledger Account Contact (requires HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT):

bool handle_provide_ledger_account(const ledger_account_t *account)
Handle called to store a verified Ledger Account contact.

Core Crypto Functions

Key functions provided by the Address Book module:

See the source files for detailed API documentation.