wsc - WebAssembly Signature Component

Sign in the cloud. Verify anywhere.

A tool and library for signing WebAssembly modules with embedded signatures that can be verified completely offline - perfect for embedded systems, edge devices, and air-gapped environments.

Why wsc?

Unlike OCI registry signatures (Cosign) that require network access at verification time, wsc embeds signatures directly in the WASM module. This enables:

About

wsc is an enhanced WebAssembly signing toolkit built on the foundation of wasmsign2 by Frank Denis. While maintaining compatibility with the WebAssembly modules signatures proposal, wsc adds production-oriented features:

• Offline-First Verification: Embedded signatures survive distribution - no network required at runtime
• Keyless Signing: Full Sigstore/Fulcio/Rekor integration with OIDC authentication (GitHub Actions, Google Cloud, GitLab CI)
• Keyless Verification: Verify Sigstore signatures offline with certificate chain and SET validation
• Enhanced Rekor Verification: Checkpoint-based verification with security hardening
• Bazel Integration: Full BUILD and MODULE.bazel support for hermetic builds
• WIT Component Model: Both library (wsc-component.wasm) and CLI (wsc-cli.wasm) builds

About This Project

wsc is based on wasmsign2 by Frank Denis, a reference implementation of the WebAssembly modules signatures proposal.

We plan to add additional features to support production use cases, including:

• Enhanced Rekor verification with checkpoint-based proofs
• Bazel build system integration for hermetic builds
• WebAssembly Component Model (WIT) support
• Expanded keyless signing capabilities
• Additional security hardening and validation

MIT License - Original wasmsign2 Copyright (c) 2024 Frank Denis

WASM Signatures

Unlike typical desktop and mobile applications, WebAssembly binaries do not embed any kind of digital signatures to verify that they come from a trusted source, and haven't been tampered with.

wsc takes an existing WebAssembly module, computes a signature for its content, and stores the signature in a custom section.

The resulting binary remains a standalone, valid WebAssembly module, but signatures can be verified prior to executing it.

wsc implements the WebAssembly modules signatures proposal. The file format is documented in the WebAssembly tool conventions repository.

The proposal, and this implementation, support domain-specific features such as:

• The ability to have multiple signatures for a single module, with a compact representation
• The ability to sign a module which was already signed with different keys
• The ability to extend an existing module with additional custom sections, without invalidating existing signatures
• The ability to verify multiple subsets of a module's sections with a single signature
• The ability to turn an embedded signature into a detached one, and the other way round

Installation

wsc is a Rust crate that can be used in other applications.

It is also a CLI tool to perform common operations, whose usage is summarized below.

Using Cargo

cargo install wsc-cli

From Source

git clone https://github.com/pulseengine/wsc.git
cd wsc
cargo build --release

Using Bazel

bazel build //src/cli:wsc

Usage

Keyless Signing (Sigstore)

wsc supports keyless signing using Sigstore - sign in CI, verify anywhere:

# Sign in GitHub Actions (or any OIDC-enabled CI)
wsc sign --keyless -i module.wasm -o signed.wasm

This will:

1. Authenticate via OIDC (GitHub Actions, Google Cloud, GitLab CI)
2. Generate an ephemeral key pair
3. Obtain a certificate from Fulcio
4. Sign the module
5. Upload signature to Rekor transparency log
6. Embed the certificate and Rekor proof in the module

Keyless Verification (Offline)

Verify a keyless-signed module - no network required:

# Basic verification (offline)
wsc verify --keyless -i signed.wasm

# With identity constraints
wsc verify --keyless -i signed.wasm \
  --cert-identity "user@example.com" \
  --cert-oidc-issuer "https://token.actions.githubusercontent.com"

Verification performs:

1. Certificate chain validation against embedded Fulcio roots
2. Rekor SET (Signed Entry Timestamp) verification
3. Identity and issuer validation (optional)

Traditional Key-Based Signing

Creating a Key Pair

wsc keygen -k secret.key -K public.key

Signing a Module

wsc sign -k secret.key -i module.wasm -o signed.wasm

Verifying a Module

wsc verify -K public.key -i signed.wasm

Inspecting a Module

wsc show -i module.wasm

Detaching/Attaching Signatures

# Detach signature to a file
wsc detach -i signed.wasm -o unsigned.wasm -S signature.bin

# Attach signature from a file
wsc attach -i unsigned.wasm -o signed.wasm -S signature.bin

Partial Verification

wsc can verify signatures for specific custom sections:

wsc verify -K public.key -i signed.wasm --split "custom_section_regex"

OpenSSH Keys Support

wsc supports OpenSSH-formatted Ed25519 keys:

# Generate SSH key
ssh-keygen -t ed25519 -f key

# Sign module (use --ssh flag)
wsc sign -k key --ssh -i module.wasm -o signed.wasm

# Verify module
wsc verify -K key.pub --ssh -i signed.wasm

GitHub Integration

Verify using a GitHub user's SSH public keys:

wsc verify --from-github username -i signed.wasm

Enhanced Features

Rekor Verification

wsc includes comprehensive Rekor inclusion proof verification:

• ✅ SET (Signed Entry Timestamp) verification
• ✅ Checkpoint-based verification with cryptographic tree state proofs
• ✅ Security hardening: Key fingerprint validation, origin validation, cross-shard attack prevention
• ✅ Defense-in-depth: 5 layers of security validation

See docs/checkpoint_security_audit.md for details.

Bazel Integration

Full Bazel support for hermetic builds:

# BUILD.bazel
load("@rules_rust//rust:defs.bzl", "rust_binary")

rust_binary(
    name = "wsc",
    srcs = ["//src/cli:wsc"],
)

See MODULE.bazel for dependency configuration.

WebAssembly Component Model

Build both library and CLI as WebAssembly components:

# Build WIT component library
bazel build //src/component:wsc-component.wasm

# Build WASI CLI binary
bazel build //src/cli:wsc-cli.wasm

Documentation

• Checkpoint Implementation - Checkpoint-based verification details
• Security Audit - Security vulnerabilities found and fixed
• Checkpoint Format - Complete format specification
• sigstore-rs Comparison - Comparison with official Rust implementation
• Security Documentation - Comprehensive security model and operational security
• Keyless Signing - Keyless signing with Sigstore/Fulcio
• Testing Guide - Testing procedures and guidelines

Development Status

wsc is under active development. Core signing/verification and Rekor validation are functional. See open issues for planned enhancements.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Frank Denis - Original wasmsign2 implementation
• Sigstore Project - Keyless signing infrastructure
• WebAssembly Community - Signatures proposal and specification