feat(core): start apps via coreapp_app_entry()
What changed, and why it matters
This commit changes how apps are launched on Trezor hardware wallets. Instead of jumping directly into an app's main function, the firmware now first runs a small Core-provided entry point that sets up the app's memory allocator and then calls the app's main function. This is a structural improvement that lets Core control more of the app's startup environment, but the commit itself does not fix a known bug or vulnerability.
Treat as a normal architectural refactor. Review the new `coreapp_app_entry()` path for correctness, ensure `app_args_t` contents pushed onto the applet stack cannot be tampered with by a malicious applet, and verify that heap initialization happens before any app-controlled memory allocation. No immediate security response is indicated by the diff alone.
Security signals we found
Refactor of applet launch path
Core gains control before app code executes
Heap ownership is now set up by Core before app entry
No direct diff evidence of a vulnerability being fixed
No changelog entry supplied
Evidence from the diff
The patch refactors app loading so that app_loader_prepare_applet() starts the new task at coreapp_app_entry() rather than at the app’s own applet_main(). A new app_args_t struct is pushed onto the applet stack, carrying applet_main, heap pointer/size, and IPC buffer size. coreapp_app_entry() (in trezor_api_v1_impl.c) receives these args, then calls applet_main with the API getter. The Core header and both STM32 and Unix coreapp implementations are updated to expose coreapp_get_app_entry() instead of coreapp_get_api_getter().
Changed components
core/embed/api/trezor_api_v1_impl.ccore/embed/io/app_arena/inc/io/app_arena.hcore/embed/io/app_arena/stm32u5/app_loader.ccore/embed/io/app_arena/unix/app_loader.ccore/embed/projects/firmware/src/stm32/coreapp_header.Score/embed/sys/task/inc/sys/coreapp.hcore/embed/sys/task/stm32/coreapp.ccore/embed/sys/task/unix/coreapp.cInspect captured patch +95 / −22
### core/embed/api/trezor_api_v1_impl.c
@@ -17,6 +17,9 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
+#include <io/app_arena.h>
+
+#include "trezor_api.h"
#include "trezor_api_v1.h"
#ifndef USE_DBG_CONSOLE
@@ -49,3 +52,11 @@ const void* coreapp_api_get(uint32_t version) {
}
return NULL;
}
+
+// Entry point the loader starts a loaded app's task on (see `app_args_t`):
+// calls the app's `applet_main` with the API getter.
+int coreapp_app_entry(const app_args_t* args) {
+ typedef int (*applet_main_t)(trezor_api_getter_t api_getter);
+ applet_main_t applet_main = (applet_main_t)args->applet_main;
+ return applet_main((trezor_api_getter_t)coreapp_api_get);
+}
### core/embed/io/app_arena/inc/io/app_arena.h
@@ -236,3 +236,22 @@ ts_t app_image_get_pminfo(app_image_handle_t handle,
* @return TS_OK on success, or an error code on failure.
*/
ts_t app_get_heap(void **heap_ptr, size_t *heap_size);
+
+/**
+ * Launch arguments of a loaded app.
+ *
+ * The loader copies this structure onto the app's own stack and passes
+ * a pointer to it, as the only argument, to Core's app entry point
+ * (`coreapp_app_entry`), which sets up the app's runtime from it before
+ * calling the app's `applet_main`.
+ */
+typedef struct {
+ /** The app's own entry point (`applet_main`) */
+ void *applet_main;
+ /** Pointer to the app's heap */
+ void *heap_ptr;
+ /** Size of the app's heap, in bytes */
+ size_t heap_size;
+ /** Size of the app's IPC inbox, in bytes */
+ size_t ipc_buffer_size;
+} app_args_t;
### core/embed/io/app_arena/stm32u5/app_loader.c
@@ -22,6 +22,7 @@
#include <trezor_model.h>
#include <trezor_rtl.h>
+#include <io/app_arena.h>
#include <rtl/sizedefs.h>
#include <sys/applet.h>
#include <sys/coreapp.h>
@@ -506,9 +507,9 @@ ts_t app_loader_prepare_applet(const app_header_t* header, void* code,
RELOC_FLAG_NORMAL | RELOC_FLAG_RW_SEGMENT);
TSH_CHECK_OK(status);
- // Get entrypoint address
- void* entrypoint = map_va(&map, chdr->entry_va);
- TSH_CHECK(entrypoint != NULL, TS_EBADMSG);
+ // Get the app's own entry point address
+ void* applet_main = map_va(&map, chdr->entry_va);
+ TSH_CHECK(applet_main != NULL, TS_EBADMSG);
// Initialize applet privileges
applet_privileges_t privileges = {0};
@@ -534,16 +535,30 @@ ts_t app_loader_prepare_applet(const app_header_t* header, void* code,
map.rw_p_addr, applet);
TSH_CHECK(ok, TS_ENOMEM);
+ // Copy the launch arguments onto the applet stack
+ const app_args_t args = {
+ .applet_main = applet_main,
+ .heap_ptr = (void*)map.heap_p_addr,
+ .heap_size = map.heap_size,
+ .ipc_buffer_size = header->ipc_buffer_size,
+ };
+ void* args_copy = systask_push_data(&applet->task, &args, sizeof(args));
+ TSH_CHECK(args_copy != NULL, TS_ENOMEM);
+
// Enable coreapp TLS area swapping
systask_enable_tls(&applet->task, coreapp_get_tls_area());
systask_enable_watchdog(&applet->task, WATCHDOG_TIMEOUT);
- uint32_t api_getter = (uint32_t)coreapp_get_api_getter();
+ // Start the task in Core's own app entry point, handing it `applet_main`,
+ // rather than jumping into `applet_main` directly. Core then sets up the
+ // app's global allocator and calls `applet_main` itself.
+ void* app_entry = coreapp_get_app_entry();
+ TSH_CHECK(app_entry != NULL, TS_EBADMSG);
// Prepare the applet to run - push exception frame on the stack
- // with the entrypoint address
- ok = systask_push_call(&applet->task, entrypoint, api_getter, 0, 0);
+ // with Core's app entry point address and the launch arguments
+ ok = systask_push_call(&applet->task, app_entry, (uint32_t)args_copy, 0, 0);
TSH_CHECK(ok, TS_ENOMEM);
systask_set_mpu(systask_active());
### core/embed/io/app_arena/unix/app_loader.c
@@ -19,6 +19,7 @@
#include <trezor_rtl.h>
+#include <io/app_arena.h>
#include <sys/applet.h>
#include <sys/coreapp.h>
#include <sys/logging.h>
@@ -107,16 +108,31 @@ ts_t app_loader_prepare_applet(const app_header_t* header, void* code,
}
TSH_CHECK(applet->handle != NULL, TS_EBADMSG);
- // Get the entrypoint function from the dynamic library
- void* entrypoint = dlsym(applet->handle, "applet_main");
- TSH_CHECK(entrypoint != NULL, TS_EBADMSG);
+ // Get the app's own entry point from the dynamic library
+ void* applet_main = dlsym(applet->handle, "applet_main");
+ TSH_CHECK(applet_main != NULL, TS_EBADMSG);
bool ok = systask_init(&applet->task, 0, 0, 0, applet);
TSH_CHECK(ok, TS_ENOMEM);
- uintptr_t api_getter = (uintptr_t)coreapp_get_api_getter();
-
- ok = systask_push_call(&applet->task, entrypoint, api_getter, 0, 0);
+ // Copy the launch arguments onto the applet stack
+ const app_args_t args = {
+ .applet_main = applet_main,
+ .heap_ptr = data,
+ .heap_size = data_size,
+ .ipc_buffer_size = header->ipc_buffer_size,
+ };
+ void* args_copy = systask_push_data(&applet->task, &args, sizeof(args));
+ TSH_CHECK(args_copy != NULL, TS_ENOMEM);
+
+ // Start the task in Core's own app entry point, handing it the launch
+ // arguments (including `applet_main`), rather than jumping into
+ // `applet_main` directly. Core then sets up the app's global allocator and
+ // calls `applet_main` itself.
+ void* app_entry = coreapp_get_app_entry();
+ TSH_CHECK(app_entry != NULL, TS_EBADMSG);
+
+ ok = systask_push_call(&applet->task, app_entry, (uintptr_t)args_copy, 0, 0);
TSH_CHECK(ok, TS_ENOMEM);
cleanup:
### core/embed/projects/firmware/src/stm32/coreapp_header.S
@@ -11,7 +11,7 @@ coreapp_header:
#ifdef USE_APP_LOADING
.word _tls_section_start
.word _tls_section_size
- .word coreapp_api_get
+ .word coreapp_app_entry
#else
.word 0
.word 0
### core/embed/sys/task/inc/sys/coreapp.h
@@ -37,8 +37,9 @@ typedef struct {
mpu_area_t stack;
// TLS area
mpu_area_t tls;
- // API interface getter
- void* api_getter;
+ // Entry point Core runs on behalf of a newly loaded app (see
+ // `coreapp_get_app_entry()`)
+ void* app_entry;
// Unprivileged SAES input buffer
void* saes_input;
// Unprivileged SAES output buffer
@@ -75,7 +76,16 @@ mpu_area_t coreapp_get_tls_area(void);
#endif // TREZOR_EMULATOR
#ifdef USE_APP_LOADING
-void* coreapp_get_api_getter(void);
+// Returns the coreapp function that a loaded app's task is started on.
+//
+// The loader does not jump into the app's own `applet_main` directly.
+// Instead it schedules this coreapp function, passing it a pointer to the
+// app's launch arguments (`app_args_t`, copied onto the app's stack), which
+// include `applet_main`. That inversion lets Core run per-launch setup -- most
+// importantly claiming the app's heap for the Rust global allocator the app
+// allocates from -- before any app code executes, and it is Core, not the
+// loader, that hands the API getter to `applet_main`.
+void* coreapp_get_app_entry(void);
#endif
#endif // KERNEL_MODE
### core/embed/sys/task/stm32/coreapp.c
@@ -35,7 +35,7 @@
static mpu_area_t coreapp_code_area;
static mpu_area_t coreapp_tls_area;
-static void* coreapp_api_getter = NULL;
+static void* coreapp_app_entry_addr = NULL;
// defined in linker script
extern uint32_t _kernel_flash_end;
@@ -128,7 +128,7 @@ bool coreapp_init(applet_t* applet, uint32_t cmd, const void* arg,
// (we will need then later for extension applets)
coreapp_tls_area = header->tls;
coreapp_code_area = applet->layout.code1;
- coreapp_api_getter = header->api_getter;
+ coreapp_app_entry_addr = header->app_entry;
// Reset the applet task (stack pointer, etc.)
if (!systask_init(&applet->task, header->stack.start, header->stack.size, 0,
@@ -159,6 +159,6 @@ mpu_area_t coreapp_get_code_area(void) { return coreapp_code_area; }
mpu_area_t coreapp_get_tls_area(void) { return coreapp_tls_area; }
-void* coreapp_get_api_getter(void) { return coreapp_api_getter; }
+void* coreapp_get_app_entry(void) { return coreapp_app_entry_addr; }
#endif // USE_APPLETS && KERNEL_MODE
### core/embed/sys/task/unix/coreapp.c
@@ -33,8 +33,10 @@ static uintptr_t coreapp_emu_trampoline(uintptr_t argc, uintptr_t argv,
return (uintptr_t)coreapp_emu((int)argc, (char**)argv);
}
-// API getter function implemented in the coreapp
-extern const void* coreapp_api_get(uint32_t version);
+// App entry point implemented in the coreapp (Rust, see
+// `core/embed/api/src/lib.rs`). Called with the loaded app's launch
+// arguments; only its address is ever taken here.
+extern int coreapp_app_entry(const void* args);
bool coreapp_init(applet_t* applet, int argc, char** argv) {
const applet_privileges_t coreapp_privileges = {0};
@@ -54,7 +56,7 @@ bool coreapp_init(applet_t* applet, int argc, char** argv) {
}
#ifdef USE_APP_LOADING
-void* coreapp_get_api_getter(void) { return (void*)coreapp_api_get; }
+void* coreapp_get_app_entry(void) { return (void*)coreapp_app_entry; }
#endif
#endif // USE_APPLETSWhy this scored 27/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.