Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
identity_register.c
Go to the documentation of this file.
1/*****************************************************************************
2 * (c) 2026 Ledger SAS.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *****************************************************************************/
16
29
30/* Includes ------------------------------------------------------------------*/
31#include <string.h>
32#include "os_utils.h"
33#include "os_apdu.h"
34#include "status_words.h"
35#include "tlv_library.h"
36#include "buffer.h"
37#include "bip32.h"
38#include "address_book.h"
40#include "address_book_crypto.h"
41#include "address_book_common.h"
42#include "identity.h"
43#include "io.h"
44#include "nbgl_use_case.h"
45
46#if defined(HAVE_ADDRESS_BOOK)
47
48/* Private defines------------------------------------------------------------*/
49#define STRUCT_VERSION 0x01
50
51/* Private enumerations ------------------------------------------------------*/
52
53/* Private types, structures, unions -----------------------------------------*/
54
59
60/* Private macros-------------------------------------------------------------*/
61#define REGISTER_IDENTITY_TAGS(X) \
62 X(0x01, TAG_STRUCTURE_TYPE, handle_struct_type, ENFORCE_UNIQUE_TAG) \
63 X(0x02, TAG_STRUCTURE_VERSION, handle_struct_version, ENFORCE_UNIQUE_TAG) \
64 X(0xf0, TAG_CONTACT_NAME, handle_contact_name, ENFORCE_UNIQUE_TAG) \
65 X(0xf1, TAG_SCOPE, handle_scope, ENFORCE_UNIQUE_TAG) \
66 X(0xf2, TAG_ACCOUNT_IDENTIFIER, handle_identifier, ENFORCE_UNIQUE_TAG) \
67 X(0x23, TAG_CHAIN_ID, handle_chain_id, ENFORCE_UNIQUE_TAG) \
68 X(0x51, TAG_BLOCKCHAIN_FAMILY, handle_blockchain_family, ENFORCE_UNIQUE_TAG) \
69 X(0xf6, TAG_GROUP_HANDLE, handle_group_handle, ENFORCE_UNIQUE_TAG) \
70 X(0x29, TAG_HMAC_PROOF, handle_hmac_proof, ENFORCE_UNIQUE_TAG)
71
72/* Private variables ---------------------------------------------------------*/
73
74/* Private functions ---------------------------------------------------------*/
75
83static bool handle_struct_type(const tlv_data_t *data, void *context_ptr)
84{
85 s_identity_ctx *context = context_ptr;
86
87 UNUSED(context);
89 PRINTF("[Register Identity] Invalid STRUCTURE_TYPE value\n");
90 return false;
91 }
92 return true;
93}
94
102static bool handle_struct_version(const tlv_data_t *data, void *context_ptr)
103{
104 s_identity_ctx *context = context_ptr;
105
106 UNUSED(context);
108 PRINTF("[Register Identity] Invalid STRUCTURE_VERSION value\n");
109 return false;
110 }
111 return true;
112}
113
121static bool handle_contact_name(const tlv_data_t *data, void *context_ptr)
122{
123 s_identity_ctx *context = context_ptr;
124
126 context->state->identity.contact_name,
127 sizeof(context->state->identity.contact_name))) {
128 PRINTF("CONTACT_NAME: failed to parse\n");
129 return false;
130 }
131 return true;
132}
133
141static bool handle_scope(const tlv_data_t *data, void *context_ptr)
142{
143 s_identity_ctx *context = context_ptr;
144
146 data, context->state->identity.scope, sizeof(context->state->identity.scope))) {
147 PRINTF("SCOPE: failed to parse\n");
148 return false;
149 }
150 return true;
151}
152
160static bool handle_identifier(const tlv_data_t *data, void *context_ptr)
161{
162 s_identity_ctx *context = context_ptr;
163
164 buffer_t buf = {0};
165 if (!get_buffer_from_tlv_data(data, &buf, 1, IDENTIFIER_MAX_LENGTH)) {
166 PRINTF("IDENTIFIER: failed to extract\n");
167 return false;
168 }
169 memmove(context->state->identity.identifier, buf.ptr, buf.size);
170 context->state->identity.identifier_len = (uint8_t) buf.size;
171 return true;
172}
173
181static bool handle_chain_id(const tlv_data_t *data, void *context_ptr)
182{
183 s_identity_ctx *context = context_ptr;
184
185 return address_book_handle_chain_id(data, &context->state->identity.chain_id);
186}
187
195static bool handle_blockchain_family(const tlv_data_t *data, void *context_ptr)
196{
197 s_identity_ctx *context = context_ptr;
198
200}
201
210static bool handle_group_handle(const tlv_data_t *data, void *context_ptr)
211{
212 s_identity_ctx *context = context_ptr;
213
214 buffer_t buf = {0};
216 PRINTF("[Register Identity] GROUP_HANDLE: invalid length (expected %d bytes)\n",
218 return false;
219 }
220 memmove(context->state->group_handle, buf.ptr, GROUP_HANDLE_SIZE);
221 return true;
222}
223
232static bool handle_hmac_proof(const tlv_data_t *data, void *context_ptr)
233{
234 s_identity_ctx *context = context_ptr;
235
236 buffer_t buf = {0};
237 if (!get_buffer_from_tlv_data(data, &buf, CX_SHA256_SIZE, CX_SHA256_SIZE)) {
238 PRINTF("[Register Identity] HMAC_PROOF: invalid length (expected %d bytes)\n",
239 CX_SHA256_SIZE);
240 return false;
241 }
242 memmove(context->state->hmac_proof, buf.ptr, CX_SHA256_SIZE);
243 return true;
244}
245
246DEFINE_TLV_PARSER(REGISTER_IDENTITY_TAGS, NULL, identity_tlv_parser)
247
248
254static bool verify_fields(const s_identity_ctx *context)
255{
256 bool result = TLV_CHECK_RECEIVED_TAGS(context->received_tags,
257 TAG_STRUCTURE_TYPE,
258 TAG_STRUCTURE_VERSION,
259 TAG_CONTACT_NAME,
260 TAG_SCOPE,
261 TAG_ACCOUNT_IDENTIFIER,
262 TAG_BLOCKCHAIN_FAMILY);
263 if (!result) {
264 PRINTF("Missing mandatory fields in Register Identity descriptor!\n");
265 return false;
266 }
267 if (context->state->identity.blockchain_family == FAMILY_ETHEREUM) {
268 result = TLV_CHECK_RECEIVED_TAGS(context->received_tags, TAG_CHAIN_ID);
269 if (!result) {
270 PRINTF("Missing CHAIN_ID for Ethereum family in Register Identity descriptor!\n");
271 return false;
272 }
273 }
274 // GROUP_HANDLE and HMAC_PROOF are optional, but must be provided together
275 bool has_group_handle = TLV_CHECK_RECEIVED_TAGS(context->received_tags, TAG_GROUP_HANDLE);
276 bool has_hmac_proof = TLV_CHECK_RECEIVED_TAGS(context->received_tags, TAG_HMAC_PROOF);
277 if (has_group_handle != has_hmac_proof) {
278 PRINTF("GROUP_HANDLE and HMAC_PROOF must be provided together!\n");
279 return false;
280 }
281 return true;
282}
283
290static void print_payload(const s_identity_ctx *context)
291{
292 UNUSED(context);
293 PRINTF("****************************************************************************\n");
294 PRINTF("[Register Identity] - Retrieved Descriptor:\n");
295 PRINTF("[Register Identity] - Contact name: %s\n",
296 context->state->identity.contact_name);
297 if (context->state->identity.scope[0] != '\0') {
298 PRINTF("[Register Identity] - Contact scope: %s\n",
299 context->state->identity.scope);
300 }
301 PRINTF("[Register Identity] - Blockchain family: %s\n",
304 PRINTF("[Register Identity] - Chain ID: %llu\n",
305 context->state->identity.chain_id);
306 }
307}
308
322static bool build_and_send_response(void)
323{
324 uint8_t group_handle[GROUP_HANDLE_SIZE] = {0};
325 uint8_t hmac_proof[CX_SHA256_SIZE] = {0};
326 uint8_t hmac_rest[CX_SHA256_SIZE] = {0};
327 bool ok = false;
328
329 if (g_ab_payload.reg.active) {
330 // group_handle and HMAC_PROOF were already verified before the UI — use the
331 // pre-extracted GID directly and only compute the new HMAC_REST.
333 g_ab_payload.reg.identity.scope,
334 g_ab_payload.reg.identity.identifier,
335 g_ab_payload.reg.identity.identifier_len,
336 g_ab_payload.reg.identity.blockchain_family,
337 g_ab_payload.reg.identity.chain_id,
338 hmac_rest)) {
339 PRINTF("[Register Identity] Error: Failed to compute HMAC_REST for new address\n");
340 goto end;
341 }
342 // Echo back the verified group_handle and hmac_proof; only hmac_rest is new
343 memmove(group_handle, g_ab_payload.reg.group_handle, GROUP_HANDLE_SIZE);
344 memmove(hmac_proof, g_ab_payload.reg.hmac_proof, CX_SHA256_SIZE);
345 }
346 else {
347 if (!address_book_generate_group_handle(group_handle)) {
348 PRINTF("[Register Identity] Error: Failed to generate group handle\n");
349 goto end;
350 }
351 // group_handle layout: gid(32) | MAC(K_group, gid)(32) — use only the GID prefix here
352 const uint8_t *gid = group_handle;
354 gid, g_ab_payload.reg.identity.contact_name, hmac_proof)) {
355 PRINTF("[Register Identity] Error: Failed to compute HMAC_PROOF\n");
356 goto end;
357 }
359 g_ab_payload.reg.identity.scope,
360 g_ab_payload.reg.identity.identifier,
361 g_ab_payload.reg.identity.identifier_len,
362 g_ab_payload.reg.identity.blockchain_family,
363 g_ab_payload.reg.identity.chain_id,
364 hmac_rest)) {
365 PRINTF("[Register Identity] Error: Failed to compute HMAC_REST\n");
366 goto end;
367 }
368 }
369 ok = address_book_send_register_identity_response(group_handle, hmac_proof, hmac_rest);
370
371end:
372 explicit_bzero(group_handle, sizeof(group_handle));
373 explicit_bzero(hmac_proof, sizeof(hmac_proof));
374 explicit_bzero(hmac_rest, sizeof(hmac_rest));
375 return ok;
376}
377
383static void review_choice(bool confirm)
384{
385 if (confirm) {
386 bool ok = build_and_send_response();
387 if (!ok) {
388 PRINTF("[Register Identity] Error: Failed to build and send HMAC proof\n");
389 }
391 "Saved to your Contacts",
392 "Error during registration",
394 }
395 else {
397 }
398}
399
403static void ui_display(const s_identity_ctx *context)
404{
405 memset(&g_ab_ui.list, 0, sizeof(g_ab_ui.list));
406 g_ab_ui.list.nbPairs = 3; // name + scope + identifier
408 g_ab_ui.list.nbPairs++; // network
409 }
412 "Review contact details",
413#ifdef SCREEN_SIZE_WALLET
414 "Confirm contact details?",
415#else
416 "Confirm contact details",
417#endif
419}
420
421/* Exported functions --------------------------------------------------------*/
422
430bolos_err_t register_identity(uint8_t *buffer_in, size_t buffer_in_length)
431{
432 const buffer_t payload = {.ptr = buffer_in, .size = buffer_in_length};
433 s_identity_ctx ctx = {0};
434
435 // Init the structure
436 memset(&g_ab_payload.reg, 0, sizeof(g_ab_payload.reg));
437 ctx.state = &g_ab_payload.reg;
438
439 // Parse using SDK TLV parser — handlers write directly into g_ab_payload.reg via ctx.state
440 if (!identity_tlv_parser(&payload, &ctx, &ctx.received_tags)) {
441 PRINTF("[Register Identity] Failed to parse TLV payload\n");
442 return SWO_INCORRECT_DATA;
443 }
444 if (!verify_fields(&ctx)) {
445 return SWO_INCORRECT_DATA;
446 }
447 print_payload(&ctx);
448
449 // Validate group-handle integrity and caller ownership before showing the UI.
450 // These are input checks (wallet-supplied data) — failing here returns an error
451 // immediately; only internal crypto operations remain post-confirm.
452 if (TLV_CHECK_RECEIVED_TAGS(ctx.received_tags, TAG_GROUP_HANDLE)) {
453 g_ab_payload.reg.active = true;
455 g_ab_payload.reg.gid)) {
456 PRINTF("[Register Identity] Error: Group handle verification failed\n");
457 return SWO_SECURITY_CONDITION_NOT_SATISFIED;
458 }
460 g_ab_payload.reg.identity.contact_name,
461 g_ab_payload.reg.hmac_proof)) {
462 PRINTF("[Register Identity] Error: HMAC_PROOF verification failed\n");
463 return SWO_SECURITY_CONDITION_NOT_SATISFIED;
464 }
465 }
466
467 // Check the Identity validity according to the Coin application logic
468 if (!handle_check_register_identity(&g_ab_payload.reg.identity)) {
469 PRINTF("[Register Identity] Error: Identity rejected by coin application\n");
470 return SWO_WRONG_PARAMETER_VALUE;
471 }
472
473 // Display confirmation UI
474 ui_display(&ctx);
475 return SWO_NO_RESPONSE;
476}
477
478#endif // HAVE_ADDRESS_BOOK
@ FAMILY_ETHEREUM
#define FAMILY_AS_STR(x)
ab_ui_t g_ab_ui
void address_book_finalize_review(bool success, const char *successMsg, const char *errorMsg, nbgl_callback_t finalize)
Common handling of a confirmed Address Book review's outcome.
void address_book_handle_review_rejected(nbgl_callback_t finalize)
Common handling of a rejected Address Book review.
bool address_book_handle_blockchain_family(const tlv_data_t *data, blockchain_family_e *family)
Generic handler for blockchain family.
ab_payload_u g_ab_payload
bool address_book_handle_printable_string(const tlv_data_t *data, char *output_buffer, size_t buffer_size)
Generic handler for printable string extraction.
bool address_book_handle_chain_id(const tlv_data_t *data, uint64_t *chain_id)
Generic handler for chain ID.
void address_book_display_review(const nbgl_icon_details_t *icon, const char *reviewTitle, const char *confirmText, nbgl_choiceCallback_t choiceCallback)
Display a confirmation review for an Address Book operation.
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_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_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_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.
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.
Register / Edit Contact Name / Edit Scope / Edit Identifier.
#define TYPE_REGISTER_IDENTITY
Definition identity.h:40
#define GROUP_HANDLE_SIZE
group_handle = gid(32) | MAC(K_group, gid)(32)
Definition identity.h:48
#define IDENTIFIER_MAX_LENGTH
blockchain address or public key, raw bytes
Definition identity.h:52
static void review_choice(bool confirm)
NBGL callback invoked after the user confirms or rejects the edit.
static bool verify_fields(const s_edit_contact_name_ctx *context)
Check that all mandatory TLV tags were received.
static void ui_display(void)
Display the Edit Contact Name review screen.
#define STRUCT_VERSION
static bool handle_contact_name(const tlv_data_t *data, void *context_ptr)
Handler for tag CONTACT_NAME.
static bool handle_blockchain_family(const tlv_data_t *data, void *context_ptr)
Handler for tag BLOCKCHAIN_FAMILY.
static bool handle_hmac_proof(const tlv_data_t *data, void *context_ptr)
Handler for tag HMAC_PROOF (optional — proves ownership of an existing group).
static void review_choice(bool confirm)
NBGL callback invoked after the user confirms or rejects the registration.
bolos_err_t register_identity(uint8_t *buffer_in, size_t buffer_in_length)
Register a new identity.
static bool handle_struct_type(const tlv_data_t *data, void *context_ptr)
Handler for tag STRUCTURE_TYPE.
static bool handle_scope(const tlv_data_t *data, void *context_ptr)
Handler for tag SCOPE.
static bool handle_chain_id(const tlv_data_t *data, void *context_ptr)
Handler for tag CHAIN_ID.
static bool build_and_send_response(void)
Build and send response.
static bool handle_struct_version(const tlv_data_t *data, void *context_ptr)
Handler for tag STRUCTURE_VERSION.
static bool handle_identifier(const tlv_data_t *data, void *context_ptr)
Handler for tag ACCOUNT_IDENTIFIER.
static bool handle_group_handle(const tlv_data_t *data, void *context_ptr)
Handler for tag GROUP_HANDLE (optional — links to an existing group).
static void print_payload(const s_identity_ctx *context)
Print the received descriptor.
static bool verify_fields(const s_identity_ctx *context)
Check that all mandatory TLV tags were received.
#define REGISTER_IDENTITY_TAGS(X)
#define LARGE_ADDRESS_BOOK_ICON
Definition nbgl_icons.h:228
API of the Advanced BOLOS Graphical Library, for typical application use-cases.
uint8_t * ptr
Definition buffer.h:22
size_t size
Pointer to byte buffer.
Definition buffer.h:23
char scope[SCOPE_LENGTH]
Definition identity.h:65
blockchain_family_e blockchain_family
Definition identity.h:68
uint64_t chain_id
Mandatory when blockchain_family == FAMILY_ETHEREUM.
Definition identity.h:69
uint8_t identifier[IDENTIFIER_MAX_LENGTH]
Definition identity.h:66
uint8_t identifier_len
Definition identity.h:67
char contact_name[CONTACT_NAME_LENGTH]
Definition identity.h:64
s_register_state_t * state
TLV_reception_t received_tags
uint8_t group_handle[GROUP_HANDLE_SIZE]
uint8_t hmac_proof[CX_SHA256_SIZE]
bool tlv_enforce_u8_value(const tlv_data_t *data, uint8_t expected_value)
Enforce that a TLV data contains the expected uint8 value.
Definition tlv_library.c:38
bool get_buffer_from_tlv_data(const tlv_data_t *data, buffer_t *out, uint16_t min_size, uint16_t max_size)
Extract a sized buffer from TLV data (zero-copy).
TLV_reception_internal_t TLV_reception_t
#define DEFINE_TLV_PARSER(TAG_LIST, COMMON_HANDLER, PARSE_FUNCTION_NAME)
Creates a parser function for a given TLV use case.
struct tlv_data_s tlv_data_t
#define TLV_CHECK_RECEIVED_TAGS(received,...)