lea-improvement-proposals

• LIP: 11
• Layer: Application
• Title: Public Key Module Interface (LEA-PKMI)
• Author: Allwin Ketnawang
• Created: 2025-07-16
• Status: Proposed

Abstract

This LIP defines a standard interface for WebAssembly (WASM) modules that provide public-key cryptography functions. The LEA Public Key Module Interface (LEA-PKMI) specifies a set of required imports and exports that enable seamless integration of cryptographic modules for operations like key generation, signing, and verification within the LEA ecosystem. This standardization promotes interoperability, simplifies development, and allows for modular replacement of cryptographic implementations.

Motivation

As the LEA ecosystem grows, there is a need for a standardized way to perform public-key cryptography across different applications and environments. Without a defined interface, developers must write custom "glue code" for each specific cryptographic library, leading to duplicated effort, increased complexity, and a higher risk of implementation errors.

The LEA-PKMI provides a clear, minimal, and efficient contract between a host environment and a WASM-based cryptographic module. This allows developers to easily swap different modules (e.g., switching from an Ed25519 module to a different signature scheme) without changing the host application's code, fostering a more flexible and secure development environment.

Specification

Any WASM module compliant with LEA-PKMI MUST implement the following interface.

1. Imports

The module MUST import the following functions from the host environment under the env namespace.

• __lea_abort(line: i32)

  • Description: Called by the module to signal a fatal, unrecoverable error.
  • Parameters:
    • line: A 32-bit integer representing the source code line number where the error occurred.
  • Host Action: The host must terminate the execution environment.

• __lea_randombytes(ptr: i32, len: i32)

  • Description: Called by the module to request cryptographically secure random data.
  • Parameters:
    • ptr: A 32-bit integer representing the memory address where the host should write the random data.
    • len: A 32-bit integer specifying the number of bytes to write.
  • Host Action: The host must fill the module's linear memory at ptr with len bytes of secure random data.

2. Exports

The module MUST export the following memory and functions.

2.1. Memory

• memory: WebAssembly.Memory
  • Description: The module's linear memory. The host uses this to write input data (e.g., messages) and read output data (e.g., keys, signatures).

2.2. Allocator Functions

• __lea_malloc(size: i32): i32

  • Description: Allocates a memory block of size bytes.
  • Returns: A pointer to the start of the allocated block.

• __lea_allocator_reset()

  • Description: Resets the module's internal allocator, invalidating all pointers.

2.3. Constant Functions

• pk_bytes(): i32

  • Returns: The required size in bytes for a public key.

• sk_bytes(): i32

  • Returns: The required size in bytes for a secret key.

• signature_bytes(): i32

  • Returns: The required size in bytes for a signature.

2.4. Cryptographic Functions

These functions MUST return 0 on success and a non-zero integer on failure.

• keygen(pk_ptr: i32, sk_ptr: i32): i32

  • Description: Generates a new key pair.
  • Parameters:
    • pk_ptr: Pointer to an allocated block for the public key.
    • sk_ptr: Pointer to an allocated block for the secret key.

• sign(sig_ptr: i32, msg_ptr: i32, msg_len: i32, sk_ptr: i32): i32

  • Description: Signs a message with a secret key.
  • Parameters:
    • sig_ptr: Pointer to an allocated block for the output signature.
    • msg_ptr: Pointer to the message to be signed.
    • msg_len: The length of the message.
    • sk_ptr: Pointer to the secret key.

• verify(sig_ptr: i32, msg_ptr: i32, msg_len: i32, pk_ptr: i32): i32

  • Description: Verifies a signature against a message and public key.
  • Parameters:
    • sig_ptr: Pointer to the signature to verify.
    • msg_ptr: Pointer to the original message.
    • msg_len: The length of the message.
    • pk_ptr: Pointer to the public key.

Rationale

The design of the LEA-PKMI prioritizes simplicity, security, and performance.

• Minimalism: The interface exposes only the essential functions required for public-key cryptography. This simplifies host-side integration by providing a clear and focused set of operations.
• Language Agnostic: By using only 32-bit integer types (i32), the interface remains compatible with any host language that can interact with WebAssembly, avoiding complexities of higher-level data types.
• Explicit Memory Management: The host controls memory allocation via __lea_malloc and can reset the state with __lea_allocator_reset. This simple model avoids the need for complex memory management or garbage collection schemes across the WASM boundary.
• Host-Provided Randomness: The module relies on the host for random data via __lea_randombytes. This is a critical security decision, as generating secure randomness is a responsibility best handled by the host environment, which has direct access to system-level entropy sources.

Backwards Compatibility

This LIP introduces a new standard and does not break any existing protocols. It is intended for new cryptographic modules developed for the LEA ecosystem. Existing modules would need to be updated to comply with this interface.

Security Considerations

• Host Responsibilities: The host environment is responsible for providing a cryptographically secure random number generator (CSPRNG) for the __lea_randombytes import. A weak or predictable source of randomness will compromise all cryptographic operations. The host must also handle the __lea_abort call by safely terminating the process to prevent further execution in a potentially corrupt state.
• Module Responsibilities: The WASM module is a security-critical component. It must be carefully implemented and audited to ensure it is free of vulnerabilities. The module should perform all necessary input validation and operate with constant-time algorithms where appropriate to prevent side-channel attacks.
• Interface Security: The interface itself is designed to be simple, reducing the potential for misuse. By passing data via pointers, it avoids copying large amounts of data across the WASM boundary, which can be a source of both performance issues and vulnerabilities.

Copyright

This LIP is licensed under the MIT License.