Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
address_book_crypto.c File Reference

HMAC Proof of Registration for Address Book contacts. More...

#include <string.h>
#include <stdint.h>
#include "address_book_crypto.h"
#include "ledger_account.h"
#include "identity.h"
#include "lcx_sha256.h"
#include "lcx_rng.h"
#include "os_utils.h"
#include "os_address_book.h"
#include "io.h"
Include dependency graph for address_book_crypto.c:

Go to the source code of this file.

Macros

#define HMAC_MSG_MAX_SIZE    (GID_SIZE + 1U + (SCOPE_LENGTH - 1U) + 1U + IDENTIFIER_MAX_LENGTH + 1U + 8U)
 Maximum serialized HMAC message size.
#define HMAC_PROOF_MSG_SIZE   (GID_SIZE + 1U + (CONTACT_NAME_LENGTH - 1U))
#define HMAC_LEDGER_MSG_SIZE    (1U + (ACCOUNT_NAME_LENGTH - 1U) + 1U + (MAX_BIP32_PATH * 4U) + 1U + 8U)

Functions

static size_t serialize_hmac_msg (uint8_t *msg, size_t msg_size, const uint8_t *gid, const char *str1, const uint8_t *raw, uint8_t raw_len, bool include_family, blockchain_family_e family, uint64_t chain_id)
 Serialize an HMAC message from optional fields.
bool address_book_send_hmac_proof (uint8_t type, const uint8_t hmac_proof[CX_SHA256_SIZE])
 Send an HMAC proof response for Edit operations.
bool address_book_send_register_identity_response (const uint8_t group_handle[GROUP_HANDLE_SIZE], const uint8_t hmac_proof[CX_SHA256_SIZE], const uint8_t hmac_rest[CX_SHA256_SIZE])
 Send the Register Identity response carrying the group handle and both HMACs.
bool address_book_generate_group_handle (uint8_t group_handle[GROUP_HANDLE_SIZE])
 Generate a device-authenticated group handle.
bool address_book_verify_group_handle (const uint8_t group_handle[GROUP_HANDLE_SIZE], uint8_t gid_out[GID_SIZE])
 Verify a group handle and extract the gid.
bool address_book_compute_hmac_proof (const uint8_t gid[GID_SIZE], const char *name, uint8_t hmac_out[CX_SHA256_SIZE])
 Compute HMAC_PROOF for an Identity contact.
bool address_book_verify_hmac_proof (const uint8_t gid[GID_SIZE], const char *name, const uint8_t hmac_expected[CX_SHA256_SIZE])
 Verify HMAC_PROOF for an Identity contact.
bool address_book_compute_hmac_rest (const uint8_t gid[GID_SIZE], const char *scope, const uint8_t *identifier, uint8_t identifier_len, blockchain_family_e family, uint64_t chain_id, uint8_t hmac_out[CX_SHA256_SIZE])
 Compute HMAC_REST for an Identity contact.
bool address_book_verify_hmac_rest (const uint8_t gid[GID_SIZE], const char *scope, const uint8_t *identifier, uint8_t identifier_len, blockchain_family_e family, uint64_t chain_id, const uint8_t hmac_expected[CX_SHA256_SIZE])
 Verify HMAC_REST for an Identity contact.
static size_t serialize_ledger_account_msg (uint8_t *msg, size_t msg_size, const char *name, const path_bip32_t *bip32_path, blockchain_family_e family, uint64_t chain_id)
 Serialize the Ledger Account HMAC message.
bool address_book_compute_hmac_proof_ledger_account (const char *name, const path_bip32_t *bip32_path, blockchain_family_e family, uint64_t chain_id, uint8_t hmac_out[CX_SHA256_SIZE])
 Compute an HMAC-SHA256 Proof of Registration for a Ledger Account.
bool address_book_verify_hmac_proof_ledger_account (const char *name, const path_bip32_t *bip32_path, blockchain_family_e family, uint64_t chain_id, const uint8_t hmac_expected[CX_SHA256_SIZE])
 Verify an HMAC Proof of Registration for a Ledger Account.

Detailed Description

HMAC Proof of Registration for Address Book contacts.

All HMAC key derivation and computation are delegated to two OS syscalls:

  • sys_address_book_hmac() — compute HMAC
  • sys_address_book_hmac_verify() — verify HMAC (constant-time)

This file is responsible only for serializing the HMAC message before calling the appropriate syscall.

Definition in file address_book_crypto.c.

Macro Definition Documentation

◆ HMAC_LEDGER_MSG_SIZE

#define HMAC_LEDGER_MSG_SIZE    (1U + (ACCOUNT_NAME_LENGTH - 1U) + 1U + (MAX_BIP32_PATH * 4U) + 1U + 8U)

Buffer size for Ledger Account message: name_len(1) | name(max 32) | depth(1) | indices(4 each, max 10) | family(1) | chain_id(8)

Definition at line 59 of file address_book_crypto.c.

◆ HMAC_MSG_MAX_SIZE

#define HMAC_MSG_MAX_SIZE    (GID_SIZE + 1U + (SCOPE_LENGTH - 1U) + 1U + IDENTIFIER_MAX_LENGTH + 1U + 8U)

Maximum serialized HMAC message size.

Worst case: gid(32) + scope_len(1) + scope(32) + id_len(1) + identifier(80) + family(1) + chain_id(8) = 155 bytes

Definition at line 49 of file address_book_crypto.c.

◆ HMAC_PROOF_MSG_SIZE

#define HMAC_PROOF_MSG_SIZE   (GID_SIZE + 1U + (CONTACT_NAME_LENGTH - 1U))

Buffer size for HMAC_PROOF message: gid(32) | name_len(1) | name(max 32)

Definition at line 53 of file address_book_crypto.c.

Function Documentation

◆ address_book_compute_hmac_proof()

bool address_book_compute_hmac_proof ( const uint8_t gid[GID_SIZE],
const char * name,
uint8_t hmac_out[CX_SHA256_SIZE] )

Compute HMAC_PROOF for an Identity contact.

Serializes the HMAC message: gid(32) | name_len(1) | name Then delegates to the OS syscall.

Parameters
[in]gid32-byte wallet-generated contact ID
[in]nameContact name (null-terminated)
[out]hmac_outOutput buffer for the 32-byte HMAC
Returns
true if successful, false otherwise

Definition at line 264 of file address_book_crypto.c.

◆ address_book_compute_hmac_proof_ledger_account()

bool address_book_compute_hmac_proof_ledger_account ( const char * name,
const path_bip32_t * bip32_path,
blockchain_family_e family,
uint64_t chain_id,
uint8_t hmac_out[CX_SHA256_SIZE] )

Compute an HMAC-SHA256 Proof of Registration for a Ledger Account.

Serializes: name_len(1) | name | depth(1) | indices | family(1) [| chain_id(8)] Then delegates to the OS syscall.

Parameters
[in]nameAccount name (null-terminated)
[in]bip32_pathDerivation path of the account
[in]familyBlockchain family
[in]chain_idChain ID (ignored for non-Ethereum families)
[out]hmac_outOutput buffer for the 32-byte HMAC proof
Returns
true if successful, false otherwise

Definition at line 452 of file address_book_crypto.c.

◆ address_book_compute_hmac_rest()

bool address_book_compute_hmac_rest ( const uint8_t gid[GID_SIZE],
const char * scope,
const uint8_t * identifier,
uint8_t identifier_len,
blockchain_family_e family,
uint64_t chain_id,
uint8_t hmac_out[CX_SHA256_SIZE] )

Compute HMAC_REST for an Identity contact.

Serializes: gid(32) | scope_len(1) | scope | id_len(1) | identifier | family(1) [| chain_id(8) for FAMILY_ETHEREUM] Then delegates to the OS syscall.

Parameters
[in]gid32-byte contact ID
[in]scopeContact scope (null-terminated, may be empty)
[in]identifierRaw identifier bytes
[in]identifier_lenLength of identifier
[in]familyBlockchain family
[in]chain_idChain ID (ignored for non-Ethereum)
[out]hmac_outOutput buffer for the 32-byte HMAC
Returns
true if successful, false otherwise

Definition at line 331 of file address_book_crypto.c.

◆ address_book_generate_group_handle()

bool address_book_generate_group_handle ( uint8_t group_handle[GROUP_HANDLE_SIZE])

Generate a device-authenticated group handle.

Generates a random 32-byte gid, then authenticates it via OS syscall: group_handle = gid(32) || HMAC-SHA256(K_group, gid)(32)

Parameters
[out]group_handleOutput buffer (64 bytes): gid || MAC
Returns
true if successful, false otherwise

Definition at line 209 of file address_book_crypto.c.

◆ address_book_send_hmac_proof()

bool address_book_send_hmac_proof ( uint8_t type,
const uint8_t hmac_proof[CX_SHA256_SIZE] )

Send an HMAC proof response for Edit operations.

Response format: type(1) | hmac(32)

Parameters
[in]typeMessage type (TYPE_EDIT_CONTACT_NAME, TYPE_EDIT_IDENTIFIER, ...)
[in]hmac_proof32-byte HMAC proof
Returns
true if sent successfully, false otherwise

Definition at line 158 of file address_book_crypto.c.

◆ address_book_send_register_identity_response()

bool address_book_send_register_identity_response ( const uint8_t group_handle[GROUP_HANDLE_SIZE],
const uint8_t hmac_proof[CX_SHA256_SIZE],
const uint8_t hmac_rest[CX_SHA256_SIZE] )

Send the Register Identity response carrying the group handle and both HMACs.

Response format: TYPE_REGISTER_IDENTITY(1) | group_handle(64) | hmac_proof(32) | hmac_rest(32) = 129 B

Parameters
[in]group_handleDevice-authenticated group handle (gid || MAC)
[in]hmac_proofHMAC over (gid, name)
[in]hmac_restHMAC over (gid, scope, identifier, family [, chain_id])
Returns
true if sent successfully, false otherwise

Definition at line 182 of file address_book_crypto.c.

◆ address_book_verify_group_handle()

bool address_book_verify_group_handle ( const uint8_t group_handle[GROUP_HANDLE_SIZE],
uint8_t gid_out[GID_SIZE] )

Verify a group handle and extract the gid.

Verifies MAC(K_group, gid) via OS syscall. On success, copies gid into gid_out.

Parameters
[in]group_handle64-byte handle to verify: gid(32) || MAC(32)
[out]gid_outExtracted gid (32 bytes), only valid on success
Returns
true if the handle is authentic, false otherwise

Definition at line 235 of file address_book_crypto.c.

◆ address_book_verify_hmac_proof()

bool address_book_verify_hmac_proof ( const uint8_t gid[GID_SIZE],
const char * name,
const uint8_t hmac_expected[CX_SHA256_SIZE] )

Verify HMAC_PROOF for an Identity contact.

Parameters
[in]gid32-byte contact ID
[in]nameContact name (null-terminated)
[in]hmac_expected32-byte HMAC to verify against
Returns
true if valid, false otherwise

Definition at line 293 of file address_book_crypto.c.

◆ address_book_verify_hmac_proof_ledger_account()

bool address_book_verify_hmac_proof_ledger_account ( const char * name,
const path_bip32_t * bip32_path,
blockchain_family_e family,
uint64_t chain_id,
const uint8_t hmac_expected[CX_SHA256_SIZE] )

Verify an HMAC Proof of Registration for a Ledger Account.

Parameters
[in]nameAccount name (null-terminated)
[in]bip32_pathDerivation path of the account
[in]familyBlockchain family
[in]chain_idChain ID (0 for non-Ethereum)
[in]hmac_expected32-byte HMAC proof to verify against
Returns
true if the proof is valid, false otherwise

Definition at line 486 of file address_book_crypto.c.

◆ address_book_verify_hmac_rest()

bool address_book_verify_hmac_rest ( const uint8_t gid[GID_SIZE],
const char * scope,
const uint8_t * identifier,
uint8_t identifier_len,
blockchain_family_e family,
uint64_t chain_id,
const uint8_t hmac_expected[CX_SHA256_SIZE] )

Verify HMAC_REST for an Identity contact.

Parameters
[in]gid32-byte contact ID
[in]scopeContact scope (null-terminated)
[in]identifierRaw identifier bytes
[in]identifier_lenLength of identifier
[in]familyBlockchain family
[in]chain_idChain ID (0 for non-Ethereum)
[in]hmac_expected32-byte HMAC to verify against
Returns
true if valid, false otherwise

Definition at line 369 of file address_book_crypto.c.

◆ serialize_hmac_msg()

size_t serialize_hmac_msg ( uint8_t * msg,
size_t msg_size,
const uint8_t * gid,
const char * str1,
const uint8_t * raw,
uint8_t raw_len,
bool include_family,
blockchain_family_e family,
uint64_t chain_id )
static

Serialize an HMAC message from optional fields.

Builds the message by concatenating present fields in order:

  1. gid (32 bytes) — if gid != NULL
  2. strlen(str1) as uint8 + str1 content — if str1 != NULL
  3. raw_len as uint8 + raw bytes — if raw != NULL
  4. family as uint8 [+ chain_id big-endian] — if include_family == true
Parameters
[out]msgOutput buffer (caller must ensure sufficient size)
[in]msg_sizeSize of msg in bytes (used for bounds checking)
[in]gid32-byte group ID, or NULL to skip
[in]str1Null-terminated string (length-prefixed in output), or NULL to skip
[in]rawRaw bytes (length-prefixed in output), or NULL to skip
[in]raw_lenLength of raw in bytes (ignored if raw == NULL)
[in]include_familyWhether to append family and optional chain_id
[in]familyBlockchain family (used only if include_family == true)
[in]chain_idChain ID, appended only for FAMILY_ETHEREUM
Returns
Number of bytes written to msg, or SIZE_MAX if msg_size is too small

Definition at line 85 of file address_book_crypto.c.

◆ serialize_ledger_account_msg()

size_t serialize_ledger_account_msg ( uint8_t * msg,
size_t msg_size,
const char * name,
const path_bip32_t * bip32_path,
blockchain_family_e family,
uint64_t chain_id )
static

Serialize the Ledger Account HMAC message.

Builds: name_len(1) | name | depth(1) | indices(4 each, big-endian) | family(1) [| chain_id(8)]

Parameters
[out]msgOutput buffer
[in]msg_sizeSize of msg in bytes
[in]nameAccount name (null-terminated)
[in]bip32_pathDerivation path of the account
[in]familyBlockchain family
[in]chain_idChain ID, appended only for FAMILY_ETHEREUM
Returns
Number of bytes written to msg, or SIZE_MAX on error

Definition at line 411 of file address_book_crypto.c.