@cowasm/openssl

@cowasm/openssl provides a WebAssembly build of the OpenSSL 3.0.7 library for use within the CoWasm ecosystem. It serves as a foundational cryptographic library dependency, offering pre-compiled OpenSSL binaries optimized for WebAssembly execution.

Package Information

• Package Name: @cowasm/openssl
• Package Type: npm
• Language: JavaScript
• Installation: npm install @cowasm/openssl
• License: BSD-3-Clause

Core Imports

const { path } = require("@cowasm/openssl");

For ES modules:

import { path } from "@cowasm/openssl";

Basic Usage

const { path } = require("@cowasm/openssl");
const { join } = require("path");

// Get the path to OpenSSL WASM binaries
console.log("OpenSSL WASM binaries located at:", path);

// Access specific OpenSSL components
const opensslBinary = join(path, "bin", "openssl");
const libsslPath = join(path, "lib");
const headersPath = join(path, "include");

Architecture

@cowasm/openssl is designed as a WebAssembly binary distribution package:

• Build System: Compiles OpenSSL 3.0.7 source using Zig cross-compiler with CoWasm-specific patches
• WASM Integration: Includes POSIX-wasm compatibility layer for WebAssembly execution
• File Structure: Provides standard Unix-like directory layout (bin/, lib/, include/) within the WASM distribution
• Dependency Management: Integrates with @cowasm/kernel and @cowasm/posix-wasm for complete WebAssembly runtime support

Capabilities

Path Export

Provides the file system path to the compiled OpenSSL WebAssembly binaries and libraries.

/**
 * File system path to the directory containing OpenSSL WASM binaries
 * Points to the dist/wasm directory within the package
 */
const path: string;

Usage Example:

const { path } = require("@cowasm/openssl");
const fs = require("fs");

// List available OpenSSL components
console.log("OpenSSL WASM directory contents:");
console.log(fs.readdirSync(path));

// Typical output might include:
// ['bin', 'lib', 'include', 'share']

WASM Binary Structure

The compiled OpenSSL WebAssembly distribution includes:

• bin/openssl - OpenSSL command-line tool compiled for WebAssembly
• lib/ - OpenSSL libraries (libssl, libcrypto) in WebAssembly format
• include/ - OpenSSL header files for development
• share/ - Additional OpenSSL resources and documentation

Implementation Details

OpenSSL Version

• Version: 3.0.7
• Source: https://github.com/openssl/openssl/archive/refs/tags/openssl-3.0.7.tar.gz

Build Configuration

The package applies WebAssembly-specific patches and compilation flags:

• Patches Applied:
  • 00-af-unix.patch - Modifies AF_UNIX socket support for WebAssembly compatibility
  • 01-cleanup-hack.patch - Cleanup modifications for WebAssembly environment
• POSIX Integration: Includes POSIX-wasm headers for compatibility
• Compiler Flags: Optimized for size (-Oz) with WebAssembly-specific configurations

Dependencies

• @cowasm/kernel (dev) - CoWasm WebAssembly execution kernel
• @cowasm/posix-wasm (dev) - POSIX compatibility layer for WebAssembly

Common Use Cases

SSL/TLS Support for CPython

const { path } = require("@cowasm/openssl");

// CPython ssl module can locate OpenSSL libraries at this path
process.env.OPENSSL_ROOT_DIR = path;

Integration with Other CoWasm Packages

const { path } = require("@cowasm/openssl");
const { spawn } = require("child_process");

// Execute OpenSSL command-line tool in WebAssembly environment
const opensslCmd = require("path").join(path, "bin", "openssl");
// Note: Actual execution would require CoWasm runtime environment

Library Discovery

const { path } = require("@cowasm/openssl");
const { join } = require("path");

// Locate specific OpenSSL libraries
const libssl = join(path, "lib", "libssl.a");
const libcrypto = join(path, "lib", "libcrypto.a");
const headers = join(path, "include", "openssl");

Error Handling

The package exports are synchronous and do not throw exceptions under normal operation. The path export will always return a valid string pointing to the WASM distribution directory within the package.

Types

/**
 * The main export object containing the path to OpenSSL WASM binaries
 */
interface OpenSSLExports {
  /** File system path to the OpenSSL WASM distribution directory */
  path: string;
}