Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
address_book_crypto.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
28
29#include <string.h>
30#include <stdint.h>
31#include "address_book_crypto.h"
32#include "ledger_account.h"
33#include "identity.h"
34#include "lcx_sha256.h"
35#include "lcx_rng.h"
36#include "os_utils.h"
37#include "os_address_book.h"
38#include "io.h"
39
40#ifdef HAVE_ADDRESS_BOOK
41
49#define HMAC_MSG_MAX_SIZE \
50 (GID_SIZE + 1U + (SCOPE_LENGTH - 1U) + 1U + IDENTIFIER_MAX_LENGTH + 1U + 8U)
51
53#define HMAC_PROOF_MSG_SIZE (GID_SIZE + 1U + (CONTACT_NAME_LENGTH - 1U))
54
59#define HMAC_LEDGER_MSG_SIZE \
60 (1U + (ACCOUNT_NAME_LENGTH - 1U) + 1U + (MAX_BIP32_PATH * 4U) + 1U + 8U)
61
62/* Private functions ---------------------------------------------------------*/
63
85static size_t serialize_hmac_msg(uint8_t *msg,
86 size_t msg_size,
87 const uint8_t *gid,
88 const char *str1,
89 const uint8_t *raw,
90 uint8_t raw_len,
91 bool include_family,
93 uint64_t chain_id)
94{
95 size_t offset = 0;
96
97 // Optional 32-byte GID prefix
98 if (gid != NULL) {
99 if (offset + GID_SIZE > msg_size) {
100 return SIZE_MAX;
101 }
102 memmove(&msg[offset], gid, GID_SIZE);
103 offset += GID_SIZE;
104 }
105
106 // Optional length-prefixed string
107 if (str1 != NULL) {
108 uint8_t len = (uint8_t) strlen(str1);
109 if (offset + 1U + (size_t) len > msg_size) {
110 return SIZE_MAX;
111 }
112 msg[offset++] = len;
113 if (len > 0) {
114 memmove(&msg[offset], str1, len);
115 offset += len;
116 }
117 }
118
119 // Optional length-prefixed raw bytes
120 if (raw != NULL) {
121 if (offset + 1U + (size_t) raw_len > msg_size) {
122 return SIZE_MAX;
123 }
124 msg[offset++] = raw_len;
125 memmove(&msg[offset], raw, raw_len);
126 offset += raw_len;
127 }
128
129 // Optional family byte + chain_id
130 if (include_family) {
131 if (offset + 1U > msg_size) {
132 return SIZE_MAX;
133 }
134 msg[offset++] = (uint8_t) family;
135 if (family == FAMILY_ETHEREUM) {
136 if (offset + 8U > msg_size) {
137 return SIZE_MAX;
138 }
139 U8BE_ENCODE(msg, offset, chain_id);
140 offset += 8U;
141 }
142 }
143
144 return offset;
145}
146
147/* Exported functions --------------------------------------------------------*/
148
158bool address_book_send_hmac_proof(uint8_t type, const uint8_t hmac_proof[CX_SHA256_SIZE])
159{
160 size_t tx = 0;
161
162 // Response format: type(1) | hmac(32)
163 G_io_tx_buffer[tx++] = type;
164 memmove(&G_io_tx_buffer[tx], hmac_proof, CX_SHA256_SIZE);
165 tx += CX_SHA256_SIZE;
166
167 io_send_response_pointer(G_io_tx_buffer, tx, SWO_SUCCESS);
168 return true;
169}
170
183 const uint8_t hmac_proof[CX_SHA256_SIZE],
184 const uint8_t hmac_rest[CX_SHA256_SIZE])
185{
186 size_t tx = 0;
187
188 G_io_tx_buffer[tx++] = TYPE_REGISTER_IDENTITY;
189 memmove(&G_io_tx_buffer[tx], group_handle, GROUP_HANDLE_SIZE);
190 tx += GROUP_HANDLE_SIZE;
191 memmove(&G_io_tx_buffer[tx], hmac_proof, CX_SHA256_SIZE);
192 tx += CX_SHA256_SIZE;
193 memmove(&G_io_tx_buffer[tx], hmac_rest, CX_SHA256_SIZE);
194 tx += CX_SHA256_SIZE;
195
196 io_send_response_pointer(G_io_tx_buffer, tx, SWO_SUCCESS);
197 return true;
198}
199
210{
211 bool success = false;
212 uint8_t *gid = group_handle;
213 uint8_t *mac = group_handle + GID_SIZE;
214
215 cx_rng_no_throw(gid, GID_SIZE);
216 if (!sys_address_book_hmac(ADDRESS_BOOK_SALT_GROUP, gid, GID_SIZE, mac)) {
217 goto end;
218 }
219 success = true;
220
221end:
222 return success;
223}
224
236 uint8_t gid_out[GID_SIZE])
237{
238 bool success = false;
239 const uint8_t *gid = group_handle;
240 const uint8_t *mac = group_handle + GID_SIZE;
241
242 if (!sys_address_book_hmac_verify(ADDRESS_BOOK_SALT_GROUP, gid, GID_SIZE, mac)) {
243 PRINTF("[Address Book] Group handle MAC verification failed\n");
244 goto end;
245 }
246 memmove(gid_out, gid, GID_SIZE);
247 success = true;
248
249end:
250 return success;
251}
252
265 const char *name,
266 uint8_t hmac_out[CX_SHA256_SIZE])
267{
268 uint8_t msg[HMAC_PROOF_MSG_SIZE] = {0};
269 bool success = false;
270 size_t msg_len = serialize_hmac_msg(msg, sizeof(msg), gid, name, NULL, 0, false, 0, 0);
271
272 if (msg_len == SIZE_MAX) {
273 goto end;
274 }
275 if (!sys_address_book_hmac(ADDRESS_BOOK_SALT_IDENTITY, msg, msg_len, hmac_out)) {
276 goto end;
277 }
278 success = true;
279
280end:
281 explicit_bzero(msg, sizeof(msg));
282 return success;
283}
284
294 const char *name,
295 const uint8_t hmac_expected[CX_SHA256_SIZE])
296{
297 uint8_t msg[HMAC_PROOF_MSG_SIZE] = {0};
298 bool success = false;
299 size_t msg_len = serialize_hmac_msg(msg, sizeof(msg), gid, name, NULL, 0, false, 0, 0);
300
301 if (msg_len == SIZE_MAX) {
302 goto end;
303 }
304 if (!sys_address_book_hmac_verify(ADDRESS_BOOK_SALT_IDENTITY, msg, msg_len, hmac_expected)) {
305 PRINTF("HMAC_PROOF mismatch\n");
306 goto end;
307 }
308 success = true;
309
310end:
311 explicit_bzero(msg, sizeof(msg));
312 return success;
313}
314
332 const char *scope,
333 const uint8_t *identifier,
334 uint8_t identifier_len,
335 blockchain_family_e family,
336 uint64_t chain_id,
337 uint8_t hmac_out[CX_SHA256_SIZE])
338{
339 uint8_t msg[HMAC_MSG_MAX_SIZE] = {0};
340 bool success = false;
341 size_t msg_len = serialize_hmac_msg(
342 msg, sizeof(msg), gid, scope, identifier, identifier_len, true, family, chain_id);
343
344 if (msg_len == SIZE_MAX) {
345 goto end;
346 }
347 if (!sys_address_book_hmac(ADDRESS_BOOK_SALT_IDENTITY, msg, msg_len, hmac_out)) {
348 goto end;
349 }
350 success = true;
351
352end:
353 explicit_bzero(msg, sizeof(msg));
354 return success;
355}
356
370 const char *scope,
371 const uint8_t *identifier,
372 uint8_t identifier_len,
373 blockchain_family_e family,
374 uint64_t chain_id,
375 const uint8_t hmac_expected[CX_SHA256_SIZE])
376{
377 uint8_t msg[HMAC_MSG_MAX_SIZE] = {0};
378 bool success = false;
379 size_t msg_len = serialize_hmac_msg(
380 msg, sizeof(msg), gid, scope, identifier, identifier_len, true, family, chain_id);
381
382 if (msg_len == SIZE_MAX) {
383 goto end;
384 }
385 if (!sys_address_book_hmac_verify(ADDRESS_BOOK_SALT_IDENTITY, msg, msg_len, hmac_expected)) {
386 PRINTF("HMAC_REST mismatch\n");
387 goto end;
388 }
389 success = true;
390
391end:
392 explicit_bzero(msg, sizeof(msg));
393 return success;
394}
395
396#ifdef HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT
397
411static size_t serialize_ledger_account_msg(uint8_t *msg,
412 size_t msg_size,
413 const char *name,
414 const path_bip32_t *bip32_path,
415 blockchain_family_e family,
416 uint64_t chain_id)
417{
418 size_t offset = serialize_hmac_msg(msg, msg_size, NULL, name, NULL, 0, false, 0, 0);
419 size_t tail_len;
420
421 if ((offset == SIZE_MAX) || (bip32_path == NULL) || (bip32_path->length == 0)
422 || (bip32_path->length > MAX_BIP32_PATH)
423 || (offset + 1U + (bip32_path->length * 4U) > msg_size)) {
424 return SIZE_MAX;
425 }
426 msg[offset++] = bip32_path->length;
427 for (uint8_t i = 0; i < bip32_path->length; i++) {
428 U4BE_ENCODE(msg, offset, bip32_path->path[i]);
429 offset += 4U;
430 }
431 tail_len = serialize_hmac_msg(
432 &msg[offset], msg_size - offset, NULL, NULL, NULL, 0, true, family, chain_id);
433 if (tail_len == SIZE_MAX) {
434 return SIZE_MAX;
435 }
436 return offset + tail_len;
437}
438
453 const path_bip32_t *bip32_path,
454 blockchain_family_e family,
455 uint64_t chain_id,
456 uint8_t hmac_out[CX_SHA256_SIZE])
457{
458 uint8_t msg[HMAC_LEDGER_MSG_SIZE] = {0};
459 bool success = false;
460 size_t msg_len
461 = serialize_ledger_account_msg(msg, sizeof(msg), name, bip32_path, family, chain_id);
462
463 if (msg_len == SIZE_MAX) {
464 goto end;
465 }
466 if (!sys_address_book_hmac(ADDRESS_BOOK_SALT_LEDGER_ACCOUNT, msg, msg_len, hmac_out)) {
467 goto end;
468 }
469 success = true;
470
471end:
472 explicit_bzero(msg, sizeof(msg));
473 return success;
474}
475
487 const path_bip32_t *bip32_path,
488 blockchain_family_e family,
489 uint64_t chain_id,
490 const uint8_t hmac_expected[CX_SHA256_SIZE])
491{
492 uint8_t msg[HMAC_LEDGER_MSG_SIZE] = {0};
493 bool success = false;
494 size_t msg_len
495 = serialize_ledger_account_msg(msg, sizeof(msg), name, bip32_path, family, chain_id);
496
497 if (msg_len == SIZE_MAX) {
498 goto end;
499 }
500 if (!sys_address_book_hmac_verify(
501 ADDRESS_BOOK_SALT_LEDGER_ACCOUNT, msg, msg_len, hmac_expected)) {
502 PRINTF("HMAC proof mismatch\n");
503 goto end;
504 }
505 success = true;
506
507end:
508 explicit_bzero(msg, sizeof(msg));
509 return success;
510}
511
512#endif // HAVE_ADDRESS_BOOK_LEDGER_ACCOUNT
513#endif // HAVE_ADDRESS_BOOK
blockchain_family_e
@ FAMILY_ETHEREUM
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.
#define HMAC_PROOF_MSG_SIZE
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_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.
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(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.
#define HMAC_MSG_MAX_SIZE
Maximum serialized HMAC message size.
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_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.
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_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.
#define HMAC_LEDGER_MSG_SIZE
#define MAX_BIP32_PATH
Definition bip32.h:15
Register / Edit Contact Name / Edit Scope / Edit Identifier.
#define GID_SIZE
32-byte random group ID generated by the device
Definition identity.h:47
#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
static int io_send_response_pointer(const uint8_t *ptr, size_t size, uint16_t sw)
Definition io.h:79
Random Number Generation.
SHA-2 (Secure Hash Algorithm 2).
uint32_t path[MAX_BIP32_PATH]
Definition bip32.h:19
uint8_t length
Definition bip32.h:18