Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
identity_provide_contact.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
39
40/* Includes ------------------------------------------------------------------*/
41#include <string.h>
42#include "os_utils.h"
43#include "status_words.h"
44#include "tlv_library.h"
45#include "buffer.h"
46#include "bip32.h"
47#include "address_book.h"
49#include "address_book_crypto.h"
50#include "address_book_common.h"
51#include "identity.h"
52
53#if defined(HAVE_ADDRESS_BOOK)
54
55/* Private defines------------------------------------------------------------*/
56#define STRUCT_VERSION 0x01
57
58/* Private types, structures, unions -----------------------------------------*/
59typedef struct {
62 uint8_t hmac_proof[CX_SHA256_SIZE];
63 uint8_t hmac_rest[CX_SHA256_SIZE];
66
67/* Private macros-------------------------------------------------------------*/
68#define PROVIDE_CONTACT_TAGS(X) \
69 X(0x01, TAG_STRUCTURE_TYPE, handle_struct_type, ENFORCE_UNIQUE_TAG) \
70 X(0x02, TAG_STRUCTURE_VERSION, handle_struct_version, ENFORCE_UNIQUE_TAG) \
71 X(0xf0, TAG_CONTACT_NAME, handle_contact_name, ENFORCE_UNIQUE_TAG) \
72 X(0xf1, TAG_SCOPE, handle_scope, ENFORCE_UNIQUE_TAG) \
73 X(0xf2, TAG_ACCOUNT_IDENTIFIER, handle_identifier, ENFORCE_UNIQUE_TAG) \
74 X(0xf6, TAG_GROUP_HANDLE, handle_group_handle, ENFORCE_UNIQUE_TAG) \
75 X(0x23, TAG_CHAIN_ID, handle_chain_id, ENFORCE_UNIQUE_TAG) \
76 X(0x51, TAG_BLOCKCHAIN_FAMILY, handle_blockchain_family, ENFORCE_UNIQUE_TAG) \
77 X(0x29, TAG_HMAC_PROOF, handle_hmac_proof, ENFORCE_UNIQUE_TAG) \
78 X(0xf7, TAG_HMAC_REST, handle_hmac_rest, ENFORCE_UNIQUE_TAG)
79
80/* Private variables ---------------------------------------------------------*/
81
82/* Private functions ---------------------------------------------------------*/
83
91static bool handle_struct_type(const tlv_data_t *data, void *context_ptr)
92{
93 s_provide_contact_ctx *context = context_ptr;
94
95 UNUSED(context);
97 PRINTF("[Provide Contact] Invalid STRUCTURE_TYPE value\n");
98 return false;
99 }
100 return true;
101}
102
110static bool handle_struct_version(const tlv_data_t *data, void *context_ptr)
111{
112 s_provide_contact_ctx *context = context_ptr;
113
114 UNUSED(context);
116 PRINTF("[Provide Contact] Invalid STRUCTURE_VERSION value\n");
117 return false;
118 }
119 return true;
120}
121
129static bool handle_contact_name(const tlv_data_t *data, void *context_ptr)
130{
131 s_provide_contact_ctx *context = context_ptr;
132
134 data, context->identity->contact_name, sizeof(context->identity->contact_name))) {
135 PRINTF("[Provide Contact] CONTACT_NAME: failed to parse\n");
136 return false;
137 }
138 return true;
139}
140
148static bool handle_scope(const tlv_data_t *data, void *context_ptr)
149{
150 s_provide_contact_ctx *context = context_ptr;
151
153 data, context->identity->scope, sizeof(context->identity->scope))) {
154 PRINTF("[Provide Contact] SCOPE: failed to parse\n");
155 return false;
156 }
157 return true;
158}
159
167static bool handle_identifier(const tlv_data_t *data, void *context_ptr)
168{
169 s_provide_contact_ctx *context = context_ptr;
170
171 buffer_t buf = {0};
172 if (!get_buffer_from_tlv_data(data, &buf, 1, IDENTIFIER_MAX_LENGTH)) {
173 PRINTF("[Provide Contact] IDENTIFIER: failed to extract\n");
174 return false;
175 }
176 memmove(context->identity->identifier, buf.ptr, buf.size);
177 context->identity->identifier_len = (uint8_t) buf.size;
178 return true;
179}
180
188static bool handle_group_handle(const tlv_data_t *data, void *context_ptr)
189{
190 s_provide_contact_ctx *context = context_ptr;
191
192 buffer_t buf = {0};
194 PRINTF("[Provide Contact] GROUP_HANDLE: invalid length (expected %d bytes)\n",
196 return false;
197 }
198 memmove(context->group_handle, buf.ptr, GROUP_HANDLE_SIZE);
199 return true;
200}
201
209static bool handle_chain_id(const tlv_data_t *data, void *context_ptr)
210{
211 s_provide_contact_ctx *context = context_ptr;
212
213 return address_book_handle_chain_id(data, &context->identity->chain_id);
214}
215
223static bool handle_blockchain_family(const tlv_data_t *data, void *context_ptr)
224{
225 s_provide_contact_ctx *context = context_ptr;
226
228}
229
237static bool handle_hmac_proof(const tlv_data_t *data, void *context_ptr)
238{
239 s_provide_contact_ctx *context = context_ptr;
240
241 buffer_t buf = {0};
242 if (!get_buffer_from_tlv_data(data, &buf, CX_SHA256_SIZE, CX_SHA256_SIZE)) {
243 PRINTF("[Provide Contact] HMAC_PROOF: invalid length (expected %d bytes)\n",
244 CX_SHA256_SIZE);
245 return false;
246 }
247 memmove(context->hmac_proof, buf.ptr, CX_SHA256_SIZE);
248 return true;
249}
250
258static bool handle_hmac_rest(const tlv_data_t *data, void *context_ptr)
259{
260 s_provide_contact_ctx *context = context_ptr;
261
262 buffer_t buf = {0};
263 if (!get_buffer_from_tlv_data(data, &buf, CX_SHA256_SIZE, CX_SHA256_SIZE)) {
264 PRINTF("[Provide Contact] HMAC_REST: invalid length (expected %d bytes)\n", CX_SHA256_SIZE);
265 return false;
266 }
267 memmove(context->hmac_rest, buf.ptr, CX_SHA256_SIZE);
268 return true;
269}
270
271DEFINE_TLV_PARSER(PROVIDE_CONTACT_TAGS, NULL, provide_contact_tlv_parser)
272
273
279static bool verify_fields(const s_provide_contact_ctx *context)
280{
281 bool result = TLV_CHECK_RECEIVED_TAGS(context->received_tags,
282 TAG_STRUCTURE_TYPE,
283 TAG_STRUCTURE_VERSION,
284 TAG_CONTACT_NAME,
285 TAG_SCOPE,
286 TAG_ACCOUNT_IDENTIFIER,
287 TAG_GROUP_HANDLE,
288 TAG_BLOCKCHAIN_FAMILY,
289 TAG_HMAC_PROOF,
290 TAG_HMAC_REST);
291 if (!result) {
292 PRINTF("[Provide Contact] Missing mandatory fields!\n");
293 return false;
294 }
295 if (context->identity->blockchain_family == FAMILY_ETHEREUM) {
296 result = TLV_CHECK_RECEIVED_TAGS(context->received_tags, TAG_CHAIN_ID);
297 if (!result) {
298 PRINTF("[Provide Contact] Missing CHAIN_ID for Ethereum family!\n");
299 return false;
300 }
301 }
302 return true;
303}
304
311static void print_payload(const s_provide_contact_ctx *context)
312{
313 UNUSED(context);
314 PRINTF("****************************************************************************\n");
315 PRINTF("[Provide Contact] - Retrieved Descriptor:\n");
316 PRINTF("[Provide Contact] - Contact name: %s\n", context->identity->contact_name);
317 if (context->identity->scope[0] != '\0') {
318 PRINTF("[Provide Contact] - Scope: %s\n", context->identity->scope);
319 }
320 PRINTF("[Provide Contact] - Identifier len: %d\n", context->identity->identifier_len);
321 PRINTF("[Provide Contact] - Blockchain: %s\n",
323}
324
325/* Exported functions --------------------------------------------------------*/
326
337bolos_err_t provide_contact(uint8_t *buffer_in, size_t buffer_in_length)
338{
339 const buffer_t payload = {.ptr = buffer_in, .size = buffer_in_length};
340 s_provide_contact_ctx ctx = {0};
341
342 // Init the structure
343 ctx.identity = &g_ab_payload.provide_contact;
344 memset(&g_ab_payload.provide_contact, 0, sizeof(g_ab_payload.provide_contact));
345
346 // Parse using SDK TLV parser
347 if (!provide_contact_tlv_parser(&payload, &ctx, &ctx.received_tags)) {
348 PRINTF("[Provide Contact] TLV parsing failed\n");
349 return SWO_INCORRECT_DATA;
350 }
351 if (!verify_fields(&ctx)) {
352 return SWO_INCORRECT_DATA;
353 }
354 print_payload(&ctx);
355
356 // Verify the group handle and extract the gid
357 if (!address_book_verify_group_handle(ctx.group_handle, g_ab_payload.provide_contact.gid)) {
358 PRINTF("[Provide Contact] Group handle verification failed\n");
359 return SWO_SECURITY_CONDITION_NOT_SATISFIED;
360 }
361
362 // Verify HMAC_PROOF over (gid, contact_name)
363 if (!address_book_verify_hmac_proof(g_ab_payload.provide_contact.gid,
364 g_ab_payload.provide_contact.contact_name,
365 ctx.hmac_proof)) {
366 PRINTF("[Provide Contact] HMAC_PROOF verification failed\n");
367 return SWO_SECURITY_CONDITION_NOT_SATISFIED;
368 }
369
370 // Verify HMAC_REST over (gid, scope, identifier, family[, chain_id])
371 if (!address_book_verify_hmac_rest(g_ab_payload.provide_contact.gid,
372 g_ab_payload.provide_contact.scope,
373 g_ab_payload.provide_contact.identifier,
374 g_ab_payload.provide_contact.identifier_len,
375 g_ab_payload.provide_contact.blockchain_family,
376 g_ab_payload.provide_contact.chain_id,
377 ctx.hmac_rest)) {
378 PRINTF("[Provide Contact] HMAC_REST verification failed\n");
379 return SWO_SECURITY_CONDITION_NOT_SATISFIED;
380 }
381
382 // Pass contact to the coin app for storage
383 if (!handle_provide_identity(&g_ab_payload.provide_contact)) {
384 PRINTF("[Provide Contact] Rejected by coin application\n");
385 return SWO_WRONG_PARAMETER_VALUE;
386 }
387
388 return SWO_SUCCESS;
389}
390
391#endif // HAVE_ADDRESS_BOOK
@ FAMILY_ETHEREUM
#define FAMILY_AS_STR(x)
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.
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_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_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.
bool handle_provide_identity(const identity_t *contact)
Handle called to store a verified contact.
Register / Edit Contact Name / Edit Scope / Edit Identifier.
#define TYPE_PROVIDE_CONTACT
Definition identity.h:44
#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 bool verify_fields(const s_edit_contact_name_ctx *context)
Check that all mandatory TLV tags were received.
#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.
static bool verify_fields(const s_provide_contact_ctx *context)
Check that all mandatory TLV tags were received.
bolos_err_t provide_contact(uint8_t *buffer_in, size_t buffer_in_length)
Deliver a verified contact to the coin application.
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 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.
#define PROVIDE_CONTACT_TAGS(X)
static bool handle_group_handle(const tlv_data_t *data, void *context_ptr)
Handler for tag GROUP_HANDLE.
static bool handle_hmac_rest(const tlv_data_t *data, void *context_ptr)
Handler for tag HMAC_REST.
static void print_payload(const s_provide_contact_ctx *context)
Print the received descriptor.
uint8_t * ptr
Definition buffer.h:22
size_t size
Pointer to byte buffer.
Definition buffer.h:23
Data extracted from a Register Identity TLV payload.
Definition identity.h:62
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
uint8_t hmac_rest[CX_SHA256_SIZE]
HMAC_REST — verifies scope + identifier.
uint8_t hmac_proof[CX_SHA256_SIZE]
HMAC_PROOF — verifies contact name.
uint8_t group_handle[GROUP_HANDLE_SIZE]
Group handle from wallet (verified later).
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,...)