Embedded SDK
Embedded SDK
Loading...
Searching...
No Matches
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/* Includes ------------------------------------------------------------------*/
18#include <string.h>
19#include "os_helpers.h"
20#include "os_print.h"
21#include "os_utils.h"
22#include "status_words.h"
23#include "apdu_chunks.h"
24#include "transaction_check.h"
27
28#if defined(HAVE_TX_CHECK)
29
30/* Private defines------------------------------------------------------------*/
31#define P1_DESCRIPTOR 0x00
32#define P1_OPT_IN 0x01
33
35#define TX_CHECK_WARNINGS \
36 ((1 << W3C_ISSUE_WARN) | (1 << W3C_RISK_DETECTED_WARN) | (1 << W3C_THREAT_DETECTED_WARN) \
37 | (1 << W3C_NO_THREAT_WARN))
38
39/* Private types, structures, unions -----------------------------------------*/
56
57/* Private variables ---------------------------------------------------------*/
59
60/* Private functions ---------------------------------------------------------*/
61
68static bool report_matches(const tx_check_context_t *ctx)
69{
70 if (!s_report.received) {
71 PRINTF("[TX CHECK] No report received\n");
72 return false;
73 }
74 if ((ctx == NULL) || (ctx->tx_hash == NULL)) {
75 PRINTF("[TX CHECK] No operation to bind the report to\n");
76 return false;
77 }
78 if (s_report.type != ctx->type) {
79 PRINTF("[TX CHECK] Type mismatch: %d != %d\n", s_report.type, ctx->type);
80 return false;
81 }
82 if (!handle_check_tx_report_chain_id(s_report.chain_id_received, s_report.chain_id, ctx)) {
83 PRINTF("[TX CHECK] Chain ID rejected\n");
84 return false;
85 }
86 if (!handle_check_tx_report_signer(s_report.address, s_report.address_len, ctx)) {
87 PRINTF("[TX CHECK] Signer address mismatch\n");
88 return false;
89 }
90 if (memcmp(s_report.tx_hash, ctx->tx_hash, TRANSACTION_CHECK_HASH_SIZE) != 0) {
91 PRINTF("[TX CHECK] TX_HASH mismatch: %.*H != %.*H\n",
93 s_report.tx_hash,
95 ctx->tx_hash);
96 return false;
97 }
98 // A domain hash on either side must be matched by the same one on the other side
99 if ((ctx->domain_hash != NULL) || s_report.domain_hash_received) {
100 if ((ctx->domain_hash == NULL) || !s_report.domain_hash_received
101 || (memcmp(s_report.domain_hash, ctx->domain_hash, TRANSACTION_CHECK_HASH_SIZE) != 0)) {
102 PRINTF("[TX CHECK] DOMAIN_HASH mismatch\n");
103 return false;
104 }
105 }
106 return true;
107}
108
114static const char *warning_text(void)
115{
116 switch (s_report.risk) {
118 switch (s_report.category) {
120 return "This transaction involves a suspicious address. "
121 "It might not be safe to continue.";
123 return "This transaction involves a suspicious dApp. "
124 "It might not be safe to continue.";
126 return "This transaction could end in a loss. "
127 "Check transaction details carefully before signing.";
128 default:
129 return "This transaction might be malicious. It might not be safe to "
130 "continue. Tap the QR code icon for more details.";
131 }
133 switch (s_report.category) {
135 return "This transaction involves a malicious address. "
136 "Your assets will most likely be stolen.";
138 return "This dApp is linked to a scammer. "
139 "Your assets will most likely be stolen.";
140 default:
141 return "This request is malicious. Your assets will most likely be stolen. "
142 "View full report for details.";
143 }
145 // No warning screen for the benign level
146 return NULL;
147 default:
148 return NULL;
149 }
150}
151
152/* Exported functions --------------------------------------------------------*/
157{
158 explicit_bzero(&s_report, sizeof(s_report));
159}
160
168{
170
172 PRINTF("[TX CHECK] Transaction Check is disabled\n");
173 return TX_CHECK_DISABLED;
174 }
175 if (tx_check_in_swap()) {
176 PRINTF("[TX CHECK] Not available in a swap\n");
178 }
179 // The review on screen points to the stored report
180 if (s_report.bound) {
181 PRINTF("[TX CHECK] Report bound to the review in progress\n");
183 }
185
188 PRINTF("[TX CHECK] Descriptor signature rejected with status 0x%x\n", status);
190 }
191 if (status != TLV_TRANSACTION_CHECK_SUCCESS) {
192 PRINTF("[TX CHECK] Descriptor parsing failed with status %d\n", status);
194 }
195 if (out.additional_data_received) {
196 PRINTF("[TX CHECK] Unsupported ADDITIONAL_DATA tag\n");
198 }
199 if (out.address.size > sizeof(s_report.address)) {
200 PRINTF("[TX CHECK] Address too long: %u\n", out.address.size);
202 }
203 if (!handle_check_tx_report(&out)) {
204 PRINTF("[TX CHECK] Descriptor rejected by the app\n");
206 }
207
208 s_report.chain_id_received = out.chain_id_received;
209 s_report.chain_id = out.chain_id;
210 s_report.domain_hash_received = out.domain_hash_received;
211 memmove(s_report.tx_hash, out.tx_hash.ptr, TRANSACTION_CHECK_HASH_SIZE);
212 if (out.domain_hash_received) {
213 memmove(s_report.domain_hash, out.domain_hash.ptr, TRANSACTION_CHECK_HASH_SIZE);
214 }
215 memmove(s_report.address, out.address.ptr, out.address.size);
216 s_report.address_len = (uint8_t) out.address.size;
217 strlcpy(s_report.tiny_url, out.tiny_url, sizeof(s_report.tiny_url));
218 strlcpy(s_report.partner, out.partner, sizeof(s_report.partner));
219 s_report.risk = out.risk;
220 s_report.type = out.type;
221 s_report.category = out.category;
222 s_report.received = true;
223
224 PRINTF("[TX CHECK] Report: partner=%s risk=%d category=%d type=%d url=%s\n",
225 s_report.partner,
226 s_report.risk,
227 s_report.category,
228 s_report.type,
229 s_report.tiny_url);
230 return TX_CHECK_SUCCESS;
231}
232
240{
241 // Only the result of this call may be shown, whatever the warning held before
243 warning->reportProvider = NULL;
244 warning->providerMessage = NULL;
245 warning->reportUrl = NULL;
246
248 PRINTF("[TX CHECK] Transaction Check is disabled\n");
249 return;
250 }
251 if (!report_matches(ctx)) {
252 warning->predefinedSet |= (1 << W3C_ISSUE_WARN);
253 return;
254 }
255
256 switch (s_report.risk) {
258 warning->predefinedSet |= (1 << W3C_NO_THREAT_WARN);
259 break;
261 warning->predefinedSet |= (1 << W3C_RISK_DETECTED_WARN);
262 break;
264 warning->predefinedSet |= (1 << W3C_THREAT_DETECTED_WARN);
265 break;
266 default:
267 // Out-of-range values are rejected at reception
268 warning->predefinedSet |= (1 << W3C_ISSUE_WARN);
269 return;
270 }
271 warning->reportProvider = s_report.partner;
272 warning->providerMessage = warning_text();
273 warning->reportUrl = s_report.tiny_url;
274 s_report.bound = true;
275}
276
284{
285 switch (status) {
286 case TX_CHECK_SUCCESS:
287 return SWO_SUCCESS;
288 case TX_CHECK_PENDING:
289 return SWO_NO_RESPONSE;
291 return SWO_COMMAND_CODE_NOT_SUPPORTED;
293 return SWO_COMMAND_NOT_ALLOWED;
295 return SWO_SECURITY_CONDITION_NOT_SATISFIED;
297 return SWO_INCORRECT_DATA;
298 default:
299 return SWO_INCORRECT_DATA;
300 }
301}
302
303#if defined(HAVE_TX_CHECK_APDU)
315bolos_err_t tx_check_handle_apdu(const uint8_t *buffer,
316 size_t buffer_len,
317 uint8_t p1,
318 uint8_t p2,
319 uint8_t *buffer_out,
320 size_t *buffer_out_length)
321{
322 size_t out_capacity = *buffer_out_length;
323 uint8_t *payload = NULL;
324 size_t payload_len = 0;
325
326 *buffer_out_length = 0;
327 switch (p1) {
328 case P1_DESCRIPTOR:
330 buffer,
331 buffer_len,
332 p2,
333 &payload,
334 &payload_len)) {
336 return SWO_INCORRECT_DATA;
338 return SWO_SUCCESS;
340 break;
341 }
343 &(const buffer_t){.ptr = payload, .size = payload_len, .offset = 0}));
344
345 case P1_OPT_IN:
346 if ((p2 != 0) || (buffer_len != 0)) {
347 return SWO_WRONG_P1_P2;
348 }
350 if (status != TX_CHECK_SUCCESS) {
351 return tx_check_status_to_sw(status);
352 }
353 if (out_capacity < 1) {
354 return SWO_INCORRECT_DATA;
355 }
357 *buffer_out_length = 1;
358 return SWO_SUCCESS;
359
360 default:
361 PRINTF("[TX CHECK] Unexpected P1 0x%02x\n", p1);
362 return SWO_WRONG_P1_P2;
363 }
364}
365#endif // HAVE_TX_CHECK_APDU
366#endif // HAVE_TX_CHECK
Chunked APDU payload reassembly shared by the SDK app features.
@ APDU_CHUNKS_OWNER_TRANSACTION_CHECK
Definition apdu_chunks.h:43
@ APDU_CHUNKS_ERROR
Protocol error; the payload in progress is dropped.
Definition apdu_chunks.h:37
@ APDU_CHUNKS_PENDING
More chunks needed.
Definition apdu_chunks.h:35
@ APDU_CHUNKS_COMPLETE
Full payload assembled; out_buf/out_len are valid.
Definition apdu_chunks.h:36
apdu_chunks_status_t apdu_chunks_reassemble(apdu_chunks_owner_t owner, const uint8_t *data, size_t len, uint8_t p2, uint8_t **out_buf, size_t *out_len)
Reassemble a multi-chunk APDU payload.
@ W3C_THREAT_DETECTED_WARN
Web3 Checks: Threat detected (see reportRisk field).
@ W3C_ISSUE_WARN
Web3 Checks issue (not available).
@ W3C_NO_THREAT_WARN
Web3 Checks: No Threat detected.
@ W3C_RISK_DETECTED_WARN
Web3 Checks: Risk detected (see reportRisk field).
size_t strlcpy(char *dst, const char *src, size_t size)
uint8_t * ptr
Definition buffer.h:22
size_t size
Pointer to byte buffer.
Definition buffer.h:23
The necessary parameters to build a warning page preceding a review. One can either use predefinedSet...
uint32_t predefinedSet
const char * providerMessage
Dedicated provider message. Default one will be used if NULL.
const char * reportProvider
name of the security report provider, used in some strings
const char * reportUrl
URL of the report, used in some strings.
char partner[TRANSACTION_CHECK_PARTNER_SIZE+1]
transaction_check_category_t category
char tiny_url[TRANSACTION_CHECK_URL_SIZE+1]
const uint8_t * tx_hash
transaction_check_type_t type
const uint8_t * domain_hash
transaction_check_category_t category
uint8_t address[TRANSACTION_CHECK_MAX_ADDRESS_SIZE]
uint8_t domain_hash[TRANSACTION_CHECK_HASH_SIZE]
char tiny_url[TRANSACTION_CHECK_URL_SIZE+1]
transaction_check_type_t type
transaction_check_risk_t risk
bool bound
Bound to the review in progress, until cleared.
uint8_t tx_hash[TRANSACTION_CHECK_HASH_SIZE]
char partner[TRANSACTION_CHECK_PARTNER_SIZE+1]
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.
#define TRANSACTION_CHECK_HASH_SIZE
#define TRANSACTION_CHECK_URL_SIZE
#define TRANSACTION_CHECK_PARTNER_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_LOSING_OPERATION
@ TRANSACTION_CHECK_CATEGORY_ADDRESS
@ TRANSACTION_CHECK_CATEGORY_DAPP
struct tlv_transaction_check_out_s tlv_transaction_check_out_t
@ TRANSACTION_CHECK_RISK_MALICIOUS
@ TLV_TRANSACTION_CHECK_SIGNATURE_ERROR
enum transaction_check_category_e transaction_check_category_t
tx_check_status_t tx_check_provide_descriptor(const buffer_t *payload)
Parse, verify and store a descriptor, replacing a report not bound to a review.
static tx_check_report_t s_report
#define TX_CHECK_WARNINGS
#define P1_OPT_IN
static const char * warning_text(void)
Text displayed in the warning, from the report risk and category.
uint16_t tx_check_status_to_sw(tx_check_status_t status)
Standard status word of a Transaction Check status.
void tx_check_apply_report(nbgl_warning_t *warning, const tx_check_context_t *ctx)
Bind the stored report to the operation being signed and fill the review warning.
#define P1_DESCRIPTOR
void tx_check_clear(void)
Erase the stored report.
bolos_err_t tx_check_handle_apdu(const uint8_t *buffer, size_t buffer_len, uint8_t p1, uint8_t p2, uint8_t *buffer_out, size_t *buffer_out_length)
Handle the SDK APDU: chunked descriptor (P1 0x00) or opt-in request (P1 0x01).
static bool report_matches(const tx_check_context_t *ctx)
Check that the stored report applies to the operation being signed.
Transaction Check: risk report from a security provider, displayed during the review.
@ TX_CHECK_SETTING_ENABLE
Transaction Check is enabled.
tx_check_status_t
@ TX_CHECK_PENDING
Opt-in screen displayed, the choice comes later.
@ TX_CHECK_NOT_ALLOWED
Report bound to the review in progress, swap, or app busy.
@ TX_CHECK_DISABLED
Transaction Check disabled by the user.
@ TX_CHECK_INVALID_DESCRIPTOR
Descriptor malformed or rejected by the app.
@ TX_CHECK_SUCCESS
Descriptor stored, or opt-in already done.
@ TX_CHECK_INVALID_SIGNATURE
Descriptor signature rejected.
bool handle_check_tx_report_chain_id(bool chain_id_received, uint64_t chain_id, const tx_check_context_t *ctx)
Check the report chain ID against the operation being signed.
bool handle_check_tx_report(const tlv_transaction_check_out_t *descriptor)
Validate the chain-specific fields of a received descriptor.
bool handle_tx_check_get_setting(tx_check_setting_t setting)
Read a persistent Transaction Check setting.
bool handle_check_tx_report_signer(const uint8_t *address, size_t address_len, const tx_check_context_t *ctx)
Check that the report address is the signer of the operation.
Transaction Check functions shared between the SDK sources, not exposed to the apps.
static bool tx_check_in_swap(void)
Tell whether the app runs a swap started by the Exchange app.
tx_check_status_t tx_check_opt_in_sdk_apdu(void)
Opt-in request received on the SDK APDU, whose reply is sent by the SDK.