Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
tlv_use_case_transaction_check.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
17#include <stdint.h>
18#include <string.h>
19
20#include "os_math.h"
21#include "os_utils.h"
22#include "ox_ec.h"
23#include "cx.h"
24#include "os_pki.h"
25#include "ledger_pki.h"
27
28#define TYPE_TRANSACTION_CHECK 0x09
29#define TRANSACTION_CHECK_VERSION 0x01
30
31// Parsed TLV data (internal context)
32typedef struct tlv_extracted_s {
33 // Received tags set by the parser
35
36 // Transaction Check output data
38
39 // Tags handled by the use case API and not the caller
40 uint8_t structure_type;
42
44
45 // Progressive hash of the received TLVs (except the signature tag)
46 cx_sha256_t hash_ctx;
48
49// ─────────────────────────────────────────────────────────────────────────────
50// Tag handlers
51// ─────────────────────────────────────────────────────────────────────────────
52
53static bool handle_structure_type(const tlv_data_t *data, void *tlv_extracted_ptr)
54{
55 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
56
57 return get_uint8_t_from_tlv_data(data, &tlv_extracted->structure_type);
58}
59
60static bool handle_structure_version(const tlv_data_t *data, void *tlv_extracted_ptr)
61{
62 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
63
64 return get_uint8_t_from_tlv_data(data, &tlv_extracted->structure_version);
65}
66
67static bool handle_tx_hash(const tlv_data_t *data, void *tlv_extracted_ptr)
68{
69 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
70
71 return get_buffer_from_tlv_data(data,
72 &tlv_extracted->output->tx_hash,
75}
76
77static bool handle_domain_hash(const tlv_data_t *data, void *tlv_extracted_ptr)
78{
79 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
80
81 return get_buffer_from_tlv_data(data,
82 &tlv_extracted->output->domain_hash,
85}
86
87static bool handle_address(const tlv_data_t *data, void *tlv_extracted_ptr)
88{
89 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
90
91 return get_buffer_from_tlv_data(data,
92 &tlv_extracted->output->address,
95}
96
97static bool handle_chain_id(const tlv_data_t *data, void *tlv_extracted_ptr)
98{
99 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
100
101 return get_uint64_t_from_tlv_data(data, &tlv_extracted->output->chain_id);
102}
103
104static bool handle_risk(const tlv_data_t *data, void *tlv_extracted_ptr)
105{
106 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
107
108 uint8_t value = 0;
109 if (!get_uint8_t_from_tlv_data(data, &value)) {
110 PRINTF("TX_CHECK_NORMALIZED_RISK: failed to extract\n");
111 return false;
112 }
113 if (value >= TRANSACTION_CHECK_RISK_COUNT) {
114 PRINTF("TX_CHECK_NORMALIZED_RISK: value %d out of range\n", value);
115 return false;
116 }
117 tlv_extracted->output->risk = (transaction_check_risk_t) value;
118 return true;
119}
120
121static bool handle_category(const tlv_data_t *data, void *tlv_extracted_ptr)
122{
123 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
124
125 uint8_t value = 0;
126 if (!get_uint8_t_from_tlv_data(data, &value)) {
127 PRINTF("TX_CHECK_NORMALIZED_CATEGORY: failed to extract\n");
128 return false;
129 }
131 PRINTF("TX_CHECK_NORMALIZED_CATEGORY: value %d out of range\n", value);
132 return false;
133 }
134 tlv_extracted->output->category = (transaction_check_category_t) value;
135 return true;
136}
137
138static bool handle_type(const tlv_data_t *data, void *tlv_extracted_ptr)
139{
140 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
141
142 uint8_t value = 0;
143 if (!get_uint8_t_from_tlv_data(data, &value)) {
144 PRINTF("TX_CHECK_SIMULATION_TYPE: failed to extract\n");
145 return false;
146 }
147 if (value >= TRANSACTION_CHECK_TYPE_COUNT) {
148 PRINTF("TX_CHECK_SIMULATION_TYPE: value %d out of range\n", value);
149 return false;
150 }
151 tlv_extracted->output->type = (transaction_check_type_t) value;
152 return true;
153}
154
155static bool handle_provider_msg(const tlv_data_t *data, void *tlv_extracted_ptr)
156{
157 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
158
159 if (!get_string_from_tlv_data(data,
160 tlv_extracted->output->provider_msg,
161 0,
162 sizeof(tlv_extracted->output->provider_msg))) {
163 PRINTF("TX_CHECK_PROVIDER_MESSAGE: failed to extract\n");
164 return false;
165 }
166 if (!is_printable_string(tlv_extracted->output->provider_msg,
167 strlen(tlv_extracted->output->provider_msg))) {
168 PRINTF("TX_CHECK_PROVIDER_MESSAGE: not printable\n");
169 return false;
170 }
171 return true;
172}
173
174static bool handle_tiny_url(const tlv_data_t *data, void *tlv_extracted_ptr)
175{
176 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
177
179 data, tlv_extracted->output->tiny_url, 0, sizeof(tlv_extracted->output->tiny_url))) {
180 PRINTF("TX_CHECK_TINY_URL: failed to extract\n");
181 return false;
182 }
183 if (!is_printable_string(tlv_extracted->output->tiny_url,
184 strlen(tlv_extracted->output->tiny_url))) {
185 PRINTF("TX_CHECK_TINY_URL: not printable\n");
186 return false;
187 }
188 return true;
189}
190
191static bool handle_signature(const tlv_data_t *data, void *tlv_extracted_ptr)
192{
193 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
194
195 return get_buffer_from_tlv_data(data,
196 &tlv_extracted->input_sig,
197 CX_ECDSA_SHA256_SIG_MIN_ASN1_LENGTH,
198 CX_ECDSA_SHA256_SIG_MAX_ASN1_LENGTH);
199}
200
201// ─────────────────────────────────────────────────────────────────────────────
202// TLV parser macro
203// ─────────────────────────────────────────────────────────────────────────────
204
205static bool handle_common(const tlv_data_t *data, void *tlv_extracted_ptr);
206
207// clang-format off
208#define TRANSACTION_CHECK_TLV_TAGS(X) \
209 X(0x01, TAG_STRUCTURE_TYPE, handle_structure_type, ENFORCE_UNIQUE_TAG) \
210 X(0x02, TAG_STRUCTURE_VERSION, handle_structure_version, ENFORCE_UNIQUE_TAG) \
211 X(0x22, TAG_ADDRESS, handle_address, ENFORCE_UNIQUE_TAG) \
212 X(0x23, TAG_CHAIN_ID, handle_chain_id, ENFORCE_UNIQUE_TAG) \
213 X(0x27, TAG_TX_HASH, handle_tx_hash, ENFORCE_UNIQUE_TAG) \
214 X(0x28, TAG_DOMAIN_HASH, handle_domain_hash, ENFORCE_UNIQUE_TAG) \
215 X(0x80, TAG_NORMALIZED_RISK, handle_risk, ENFORCE_UNIQUE_TAG) \
216 X(0x81, TAG_NORMALIZED_CATEGORY, handle_category, ENFORCE_UNIQUE_TAG) \
217 X(0x82, TAG_PROVIDER_MSG, handle_provider_msg, ENFORCE_UNIQUE_TAG) \
218 X(0x83, TAG_TINY_URL, handle_tiny_url, ENFORCE_UNIQUE_TAG) \
219 X(0x84, TAG_SIMULATION_TYPE, handle_type, ENFORCE_UNIQUE_TAG) \
220 X(0x85, TAG_ADDITIONAL_DATA, NULL, ENFORCE_UNIQUE_TAG) \
221 X(0x15, TAG_DER_SIGNATURE, handle_signature, ENFORCE_UNIQUE_TAG)
222// clang-format on
223
224DEFINE_TLV_PARSER(TRANSACTION_CHECK_TLV_TAGS, &handle_common, parse_transaction_check_tlv)
225
226
229static bool handle_common(const tlv_data_t *data, void *tlv_extracted_ptr)
230{
231 tlv_extracted_t *tlv_extracted = tlv_extracted_ptr;
232
233 if (data->tag != TAG_DER_SIGNATURE) {
234 CX_ASSERT(
235 cx_hash_update((cx_hash_t *) &tlv_extracted->hash_ctx, data->raw.ptr, data->raw.size));
236 }
237 return true;
238}
239
240// ─────────────────────────────────────────────────────────────────────────────
241// Verification
242// ─────────────────────────────────────────────────────────────────────────────
243
245{
246 // Check structure type tag present
247 if (!TLV_CHECK_RECEIVED_TAGS(tlv_extracted->received_tags, TAG_STRUCTURE_TYPE)) {
248 PRINTF("Error: no struct type specified!\n");
250 }
251
252 if (tlv_extracted->structure_type != TYPE_TRANSACTION_CHECK) {
253 PRINTF("Error: unexpected struct type %d\n", tlv_extracted->structure_type);
255 }
256
257 // Check mandatory fields
258 if (!TLV_CHECK_RECEIVED_TAGS(tlv_extracted->received_tags,
259 TAG_STRUCTURE_VERSION,
260 TAG_TX_HASH,
261 TAG_ADDRESS,
262 TAG_NORMALIZED_RISK,
263 TAG_NORMALIZED_CATEGORY,
264 TAG_TINY_URL,
265 TAG_SIMULATION_TYPE,
266 TAG_DER_SIGNATURE)) {
267 PRINTF("Error: missing mandatory tags in Transaction Check TLV\n");
269 }
270
271 // Version check
272 if (tlv_extracted->structure_version != TRANSACTION_CHECK_VERSION) {
273 PRINTF("Error: unsupported Transaction Check version %d\n",
274 tlv_extracted->structure_version);
276 }
277
278 // Forward optional field reception flags
279 tlv_extracted->output->chain_id_received
280 = TLV_CHECK_RECEIVED_TAGS(tlv_extracted->received_tags, TAG_CHAIN_ID);
281 tlv_extracted->output->domain_hash_received
282 = TLV_CHECK_RECEIVED_TAGS(tlv_extracted->received_tags, TAG_DOMAIN_HASH);
283 tlv_extracted->output->provider_msg_received
284 = TLV_CHECK_RECEIVED_TAGS(tlv_extracted->received_tags, TAG_PROVIDER_MSG);
285 tlv_extracted->output->additional_data_received
286 = TLV_CHECK_RECEIVED_TAGS(tlv_extracted->received_tags, TAG_ADDITIONAL_DATA);
287
289}
290
292{
293 // Finalize the SHA-256 hash
294 uint8_t tlv_hash[CX_SHA256_SIZE] = {0};
295 CX_ASSERT(cx_hash_final((cx_hash_t *) &tlv_extracted->hash_ctx, tlv_hash));
296 buffer_t hash = {.ptr = tlv_hash, .size = sizeof(tlv_hash)};
297
298 // Verify with PKI
299 uint8_t expected_key_usage = CERTIFICATE_PUBLIC_KEY_USAGE_TX_SIMU_SIGNER;
300 cx_curve_t expected_curve = CX_CURVE_SECP256K1;
301
304 hash, &expected_key_usage, &expected_curve, tlv_extracted->input_sig);
306 PRINTF("Failed to verify Transaction Check signature\n");
308 }
309
311}
312
313// ─────────────────────────────────────────────────────────────────────────────
314// Public API
315// ─────────────────────────────────────────────────────────────────────────────
316
319{
320 // Initialize the parsing context
321 tlv_extracted_t tlv_extracted = {0};
322 tlv_extracted.output = out;
323
324 // Reset output
325 memset(out, 0, sizeof(*out));
326
327 // Initialize the progressive SHA-256 hash
328 CX_ASSERT(cx_sha256_init_no_throw(&tlv_extracted.hash_ctx));
329
330 // Parse the TLV payload
331 if (!parse_transaction_check_tlv(payload, &tlv_extracted, &tlv_extracted.received_tags)) {
332 PRINTF("Failed to parse Transaction Check TLV payload\n");
334 }
335
336 // Verify structural integrity
337 tlv_transaction_check_status_t err = verify_struct(&tlv_extracted);
339 PRINTF("Failed to verify Transaction Check TLV structure\n");
340 return err;
341 }
342
343 // Verify PKI signature
344 err = verify_signature(&tlv_extracted);
346 PRINTF("Failed to verify Transaction Check signature\n");
347 return err;
348 }
349
350 // Retrieve partner name from the PKI certificate
351 uint8_t key_usage = 0;
352 size_t trusted_name_len = 0;
353 uint8_t trusted_name[CERTIFICATE_TRUSTED_NAME_MAXLEN] = {0};
354 cx_ecfp_384_public_key_t public_key = {0};
355 if (os_pki_get_info(&key_usage, trusted_name, &trusted_name_len, &public_key) == 0) {
356 if (trusted_name_len > sizeof(trusted_name)) {
357 PRINTF("Invalid certificate name length: %u\n", trusted_name_len);
359 }
360 PRINTF("Using certificate name as partner name\n");
361 // The certificate name is not NUL-terminated
362 size_t copy_len = MIN(trusted_name_len, sizeof(out->partner) - 1);
363 memcpy(out->partner, trusted_name, copy_len);
364 out->partner[copy_len] = '\0';
365 }
366 // Set a default value for partner
367 if (strlen(out->partner) == 0) {
368 PRINTF("Using default name as partner name\n");
369 snprintf(out->partner, sizeof(out->partner), "Transaction Checks");
370 }
371
373}
check_signature_with_pki_status_t check_signature_with_pki(const buffer_t hash, const uint8_t *expected_key_usage, const cx_curve_t *expected_curve, const buffer_t signature)
Checks a signature using the PKI certificate.
Definition ledger_pki.c:5
@ CHECK_SIGNATURE_WITH_PKI_SUCCESS
Definition ledger_pki.h:7
enum check_signature_with_pki_status_e check_signature_with_pki_status_t
#define MIN(x, y)
Definition nbgl_types.h:131
tlv_dynamic_descriptor_out_t * output
char partner[TRANSACTION_CHECK_PARTNER_SIZE+1]
bool get_string_from_tlv_data(const tlv_data_t *data, char *out, uint16_t min_length, uint16_t out_size)
Copy a NUL-terminated string from TLV data.
bool get_uint64_t_from_tlv_data(const tlv_data_t *data, uint64_t *value)
Extract a uint64_t value from TLV data.
Definition tlv_library.c:64
bool get_uint8_t_from_tlv_data(const tlv_data_t *data, uint8_t *value)
Extract a uint8_t value from TLV data.
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,...)
struct tlv_extracted_s tlv_extracted_t
static bool handle_common(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_domain_hash(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_structure_version(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_provider_msg(const tlv_data_t *data, void *tlv_extracted_ptr)
#define TRANSACTION_CHECK_TLV_TAGS(X)
static bool handle_category(const tlv_data_t *data, void *tlv_extracted_ptr)
static tlv_transaction_check_status_t verify_signature(tlv_extracted_t *tlv_extracted)
static bool handle_tiny_url(const tlv_data_t *data, void *tlv_extracted_ptr)
tlv_transaction_check_status_t tlv_use_case_transaction_check(const buffer_t *payload, tlv_transaction_check_out_t *out)
Parse a Transaction Check TLV payload.
static bool handle_type(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_chain_id(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_structure_type(const tlv_data_t *data, void *tlv_extracted_ptr)
#define TRANSACTION_CHECK_VERSION
static bool handle_common(const tlv_data_t *data, void *tlv_extracted_ptr)
Common handler called for all tags to progressively hash them (except signature).
static tlv_transaction_check_status_t verify_struct(const tlv_extracted_t *tlv_extracted)
static bool handle_tx_hash(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_signature(const tlv_data_t *data, void *tlv_extracted_ptr)
static bool handle_risk(const tlv_data_t *data, void *tlv_extracted_ptr)
#define TYPE_TRANSACTION_CHECK
static bool handle_address(const tlv_data_t *data, void *tlv_extracted_ptr)
#define TRANSACTION_CHECK_HASH_SIZE
#define TRANSACTION_CHECK_MIN_ADDRESS_SIZE
enum transaction_check_risk_e transaction_check_risk_t
#define TRANSACTION_CHECK_MAX_ADDRESS_SIZE
enum tlv_transaction_check_status_e tlv_transaction_check_status_t
enum transaction_check_type_e transaction_check_type_t
@ TRANSACTION_CHECK_CATEGORY_COUNT
struct tlv_transaction_check_out_s tlv_transaction_check_out_t
@ TLV_TRANSACTION_CHECK_SIGNATURE_ERROR
@ TLV_TRANSACTION_CHECK_UNKNOWN_VERSION
@ TLV_TRANSACTION_CHECK_MISSING_STRUCTURE_TAG
@ TLV_TRANSACTION_CHECK_MISSING_TAG
@ TLV_TRANSACTION_CHECK_PARSING_ERROR
enum transaction_check_category_e transaction_check_category_t