DOCSEARCHbyAlgolia
Submit Docs

Wasefire

repository·main·Indexed 41 days ago

https://github.com/google/wasefire

A research-oriented, experimental platform for running WebAssembly applets in firmware environments to improve accessibility and security. It provides a CLI for managing Rust-based applets, a low-level applet API (wasefire-applet-api v0.9.1-git), and support for the nRF52840-dk (nordic) and Linux (host) boards.

Tokens
101K
Snippets
351
Records
455
Agent score
50%

What's inside Wasefire

  1. Supported boards for the Wasefire Runner

    main

    The Wasefire Runner currently supports two specific board configurations:

    • nordic: Targeted for the nRF52840-dk hardware.
    • host: Targeted for Linux environments.

    Note that support for the host board may vary depending on the specific Linux distribution or environment configuration.

  2. Supported boards and applet languages

    main

    Wasefire supports specific hardware boards and programming languages for applet development.

    Supported Boards

    A board is considered supported if it has a Runner. Currently supported boards include:

    • Linux (useful for testing without physical hardware)
    • nRF52840
    • OpenTitan

    Supported Applet Languages

    An applet language is supported if it has a Prelude. Currently supported languages include:

    • Rust

    Note: When running multiple applets concurrently on the same platform, they do not need to be written in the same language to inter-operate.

  3. Manage applets and platforms with Wasefire CLI

    main

    The Wasefire CLI provides several commands for managing applets and platform states. Key commands include:

    Applet Management

    • applet-install / applet-uninstall: Manage applet lifecycle.
    • applet-reboot: Reboot a specific applet.
    • applet-rpc: Execute RPCs on an applet. Use the --repl flag with {applet,platform}-rpc to enable REPL mode where input is split by lines.
    • applet-exit-status: Retrieve the exit status of an applet.

    Platform Management

    • platform-list: List available platforms.
    • platform-info: Print platform serial and version.
    • platform-reboot: Reboot the platform.
    • platform-clear-store: Clear the platform store.
    • platform-lock: Lock a platform protocol.
    • platform-rpc: Execute vendor-specific platform RPCs.
    • platform-update: Perform A/B platform updates (takes a bundle in 0.5.0-git).

    Development and Host

    • host: Start a host platform.
    • rust-applet-build / rust-applet-install: Build and install Rust applets. Use --crate-dir to specify the crate directory for build/test operations.

  4. Access Wasefire project resources and documentation

    main

    You can find official Wasefire resources, including the website, source code, and community mailing list, via the following links:

    For technical implementation, refer to the following API documentation:

    If you have general questions, consult the FAQ.

  5. Understand the Wasefire Applet Execution Model

    main

    Wasefire applets are not executed as native code. Instead, they are installed as WebAssembly byte-code. This allows the platform to leverage the static guarantees provided by WebAssembly.

    Execution occurs via an interpreter that can run directly from the byte-code or from an optimized representation stored in flash or RAM (which may be computed ahead-of-time or on-demand).

  6. Understand the mapping convention of the wasm API bindings

    main

    The bindings in the api crate are generated from procedural descriptions in the api-desc crate and follow these specific mapping rules:

    • Module Hierarchy: The module hierarchy in the applet API is mirrored exactly in this crate.
    • Type Definitions: Enums are mapped to their definitions. If an enum is used as an error, it includes a Error::to_result(isize) -> Result<usize, Error> method to convert signed integer results from Wasm into a Rust Result.
    • Function Mapping: Every function is mapped to its definition and also to a module of the same name. This module contains two structs:
      • Params: For the function's parameters.
      • Results: For the function's return values. (Note: If a struct is empty, it is not used.)
    • Data Types: All parameters and results are 32-bit integers mapping to the Wasm i32 type, but the Rust types reflect their semantic role:
      • usize for unsigned integers.
      • isize for signed integers (often used for Result<u31, u31> patterns).
      • *const u8 and *mut u8 for opaque or polymorphic pointers.
      • *const T and *mut T for transparent pointers where T is recursively defined.
      • extern "C" fn(data: *const u8, ...) for closures over opaque data.

  8. Understand Wasefire core terminology

    main

    To work with Wasefire, you must understand the relationship between hardware, software, and the abstraction layers that connect them:

    • Device: The final product, encompassing hardware, configuration, and the set of applets (firmware) that define its functionality.
    • User: The entity (person, team, or organization) owning the Device and responsible for its design, development, and lifetime management.
    • Board: The physical hardware of the Device.
    • Applet: A piece of software implementing a specific function. Applets are compiled into WebAssembly (Wasm) and run concurrently.
    • Runner: A binary that implements the Board API and calls the Scheduler.
    • Scheduler: The software implementing platform logic. It sits between the Board API and the Applet API and is responsible for security properties.
    • Platform: The complete firmware binary composed of a Runner and the Scheduler.
    • Prelude: A language-specific library (e.g., for Rust) that provides a safe, high-level interface to the Applet API.

  9. Use Key-Value Store operations: insert, find, and remove

    main

    The store supports three primary operations. Each operation has a standard version for single keys and a fragmented variant for handling ranges of keys (abstract keys) to support large values.

    Operations

    • insert: Adds a value to the store. If the key (or range of keys) is already present, the existing value is overwritten.
    • remove: Deletes a key (or range of keys) from the store. Removing a key that does not exist is not considered an error.
    • find: Retrieves the value associated with a key (or range of keys).
      • If the key is present, it returns the bytes of the value.
      • If the key is absent, it returns None (or a 'Not found' status in text interfaces).

    In text-based RPC implementations, find typically attempts to convert the retrieved byte slice into a string for output.

  10. Use the applet prelude instead of the low-level API

    main
    When developing applets for Wasefire, avoid using the wasefire-applet-api directly. The raw API is a low-level interface that corresponds to the WebAssembly level. Instead, use the language-specific prelude provided by Wasefire, which offers a more ergonomic and idiomatic developer experience for your programming language.

  11. Understand Wasefire stability and support

    main

    Wasefire is a research project and is considered experimental.

    Key stability notes:

    • No Guarantees: The project does not provide any guarantees.
    • Unstable Crates: Currently, all crates are considered unstable.
    • Versioning: The project attempts to follow cargo SemVer guidelines for its crates.
    • Support Disclaimer: This is not an officially supported Google product and is not eligible for rewards under the Google Open Source Software Vulnerability Rewards Program.

  12. Understand Applet Resource Footprint and Performance

    main

    Wasefire is designed for micro-controllers and embedded environments with the following characteristics:

    Interpreter Size

    • Size-optimized: ~22kB
    • Speed-optimized: ~66kB

    Performance Strategy

    • Computation: Intensive tasks like cryptography are offloaded to hardware or native code within the platform.
    • Logic: Applets are intended for business logic rather than compute-intensive operations.
    • Memory: The interpreter is designed for minimal RAM overhead. WebAssembly byte-code is generally more compact than native code, offering a footprint benefit.