Farscape Entry Points

Farscape's Modular Entry Points

This article was originally published on the SpeakEZ Technologies blog as part of our early design work on the Fidelity Framework. It has been updated to reflect the Clef language naming and current project structure.

The Fidelity framework’s Farscape CLI addresses a pressing challenge in modern software development: how to enhance the safety of battle-tested C/C++ tools without disrupting the countless systems that depend on them. Every day, organizations rely on command-line tools like OpenSSL, libzip, and many others that represent decades of engineering expertise but carry the inherent memory safety risks of their C/C++ heritage. Building on Farscape’s current capability – generating [<FidelityExtern>] attributed Clef binding declarations from C headers – the “shadow-api” design vision extends the tool toward a more ambitious goal: generating drop-in replacements for critical tools that maintain perfect compatibility while adding comprehensive type and memory safety guarantees.

These aren’t just bindings or wrappers. They’re transparent recompilations to native binaries capable of passing the same integration tests, processing the same inputs, and producing identical outputs to their C/C++ predecessors. Crucially, the safety abstractions employ Clef’s zero-cost abstraction principles, where all type safety and bounds checking compile away to efficient native code, unlike many C++ safety extensions or custom compiler approaches that can impose significant runtime overhead.

Farscape’s Dual Approach

Farscape serves two complementary modes for enhancing C/C++ code safety:

standard-lib mode (implemented): Creates [<FidelityExtern>] attributed Clef binding declarations and Layer 2 idiomatic wrappers that integrate C/C++ libraries directly into Fidelity applications. Farscape uses clang’s two-pass parsing with XParsec post-processing, and the [<FidelityExtern>] attribute carries library name and symbol metadata through the entire pipeline so Alex can emit MLIR with appropriate binding strategy attributes. Current focus is libc dynamic binding.

shadow-api mode (design vision): Extends the standard-lib foundation to generate complete Fidelity projects that compile to drop-in replacements for existing command-line tools, maintaining perfect external compatibility while providing comprehensive internal safety guarantees.

The shadow-api mode represents the more ambitious vision: enabling organizations to enhance the safety of their critical infrastructure tools without changing a single script, build file, or operational procedure.

  graph TD
    subgraph Original["Original C/C++ Tool"]
        CTOOL[C/C++ Binary]
        UNSAFECODE[Memory Unsafe Code]
        CAPI[Command-Line Interface]
    end

    subgraph FarscapeProcess["Farscape shadow-api Generation"]
        ANALYZE[Header & Binary Analysis]
        CODEGEN[Type-Safe Clef Generation]
        SAFETY[Memory Safety Integration]
        COMPILE[Composer Compilation]
    end

    subgraph SafeReplacement["Drop-In Replacement"]
        SAFETOOL[Type-Safe Binary]
        SAMEAPI[Identical CLI Interface]
        COMPATIBLE[100% Compatible Behavior]
    end

    Original --> FarscapeProcess
    ANALYZE --> CODEGEN
    CODEGEN --> SAFETY
    SAFETY --> COMPILE
    FarscapeProcess --> SafeReplacement

The Core Use Case: OpenSSL

OpenSSL represents one of the most critical yet vulnerable pieces of infrastructure software in existence. Used everywhere from web servers to embedded devices, it provides essential cryptographic functionality through a command-line interface that systems depend on:

# Standard OpenSSL usage - interface must remain identical
openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr -subj "/CN=example.com"
openssl x509 -req -in request.csr -signkey private.key -out certificate.crt -days 365
openssl enc -aes-256-cbc -in secret.txt -out secret.enc -k mypassword
openssl dgst -sha256 document.pdf
openssl rand -hex 32

Any organization using OpenSSL has built critical processes around this exact interface. Certificates are generated using these precise commands, scripts expect specific output formats, and integration tests verify exact behavior. A true drop-in replacement must maintain perfect compatibility while eliminating the memory safety vulnerabilities that have plagued OpenSSL throughout its history.

Generating the Drop-In Replacement

Farscape transforms OpenSSL into a memory-safe equivalent through comprehensive analysis and code generation:

# Generate shadow-api replacement for OpenSSL
farscape generate --type shadow-api --headers openssl/ssl.h openssl/evp.h `
                             --libraries "ssl,crypto" `
                             --output openssl

This command analyzes both the OpenSSL binary interface and its underlying libraries, producing a complete Fidelity project structure:

openssl_safe/
|-- OpenSSLSafe.fidproj       # Fidelity project configuration
|-- src/
|   |-- main.clef               # Main entry point with command routing
|   |-- keygen.clef            # RSA/DSA key generation
|   |-- certificates.clef      # X.509 certificate operations
|   |-- encryption.clef        # Symmetric encryption operations
|   |-- hashing.clef           # Cryptographic hashing
|   `-- random.clef            # Secure random number generation
|-- tests/
|   `-- compatibility.clef     # Tests ensuring OpenSSL compatibility
`-- README.md                # Generated documentation

The resulting project compiles to a binary that can literally replace the original OpenSSL executable:

# Build the safe replacement
cd openssl
clefpak build

# Deploy as drop-in replacement
sudo cp ./bin/openssl /usr/bin/openssl

# All existing scripts and processes work unchanged
./existing_script.sh  # Uses memory-safe OpenSSL transparently

Type-Safe Implementation with Perfect Compatibility

The generated Clef implementation maintains OpenSSL’s exact interface while providing comprehensive safety:

// OpenSSLSafe/src/main.clef - Drop-in compatible entry point
module OpenSSLSafe.Main

open Fidelity.Platform
open OpenSSLSafe.KeyGen
open OpenSSLSafe.Certificates
open OpenSSLSafe.Encryption

// Main entry point maintaining exact OpenSSL compatibility
[<EntryPoint>]
let main args =
    if Array.isEmpty args then
        printOpenSSLUsage()
        1
    else
        let subcommand = args.[0]
        let subArgs = Array.sub args 1 (args.Length - 1)

        match subcommand with
        | "genrsa" ->
            // Type-safe RSA key generation with identical output format
            handleGenRSA subArgs
        | "req" ->
            // Type-safe certificate request generation
            handleCertificateRequest subArgs
        | "x509" ->
            // Type-safe X.509 operations
            handleX509Operations subArgs
        | "enc" ->
            // Type-safe symmetric encryption
            handleEncryption subArgs
        | "dgst" ->
            // Type-safe hashing operations
            handleDigest subArgs
        | "rand" ->
            // Type-safe random number generation
            handleRandom subArgs
        | "version" ->
            // Maintain version compatibility while indicating safety
            printfn "OpenSSL 3.0.0 (Fidelity-Safe)"
            0
        | cmd ->
            eprintfn "openssl:Error: '%s' is an invalid command." cmd
            eprintfn ""
            printOpenSSLUsage()
            1

// Type-safe RSA key generation maintaining exact OpenSSL behavior
let handleGenRSA (args: string[]) : int =
    match parseGenRSAArgs args with
    | Ok config ->
        // Open output file descriptor (stdout if "-")
        let fd = if config.OutputFile = "-" then 1l
                 else Fidelity.Libc.IO.openFile config.OutputFile
        match generateRSAKeySafe config.KeySize config.PublicExponent with
        | Ok rsaKey ->
            match writeRSAKeyPEM rsaKey fd with
            | Ok () ->
                if config.Verbose then
                    printfn "Generating RSA private key, %d bit long modulus" config.KeySize
                0
            | Error msg ->
                eprintfn "unable to write 'random state'"
                eprintfn "%s" msg
                1
        | Error msg ->
            eprintfn "%s" msg
            1
    | Error usage ->
        eprintfn "%s" usage
        1

Comprehensive Safety Infrastructure

The shadow-api replacement provides safety guarantees impossible with the original C implementation:

// OpenSSL/src/keygen.clef - Memory-safe key generation
module OpenSSLSafe.KeyGen

open Fidelity.Platform
open FSharp.NativeInterop

// Type-safe key representation with scope-based cleanup
type SafeRSAKey = {
    KeySize: int
    Modulus: nativeptr<byte>
    ModulusLen: int
    PublicExponent: int64
    PrivateData: nativeptr<byte>
    PrivateLen: int
}

// Cryptographically secure memory clearing that won't be optimized away
let secureZero (ptr: nativeptr<byte>) (size: int) =
    for i = 0 to size - 1 do
        NativePtr.set ptr i 0uy
    // Platform-specific volatile barrier prevents optimizer from eliding the writes
    Platform.Bindings.Libc.Memory.memoryBarrier ()

// RSA key generation with compile-time validated constraints
let generateRSAKeySafe (keySize: int) (publicExp: int64) : Result<SafeRSAKey, string> =
    // These safety checks compile to zero-cost native code
    // Clef's type erasure eliminates runtime overhead for type-level guarantees
    if keySize < 1024 then
        Error "Key size too small. Minimum is 1024 bits"
    elif keySize > 16384 then
        Error "Key size too large. Maximum is 16384 bits"
    elif publicExp <> 3L && publicExp <> 65537L then
        Error "Invalid public exponent. Must be 3 or 65537"
    else
        // Use platform CSPRNG for prime generation
        let p = generateSafePrime (keySize / 2)
        let q = generateSafePrime (keySize / 2)

        // Ensure p and q are sufficiently different (OpenSSL compatibility)
        if primesTooClose p q keySize then
            Error "Generated primes too close together"
        else
            let n = bigMul p q
            let phi = bigMul (bigSub p 1L) (bigSub q 1L)

            // Calculate private exponent with bounds checking
            match modularInverse publicExp phi with
            | Some d ->
                let privateData = NativePtr.stackalloc<byte> (keySize / 8)
                encodePrivateKey d privateData

                Ok {
                    KeySize = keySize
                    Modulus = n
                    ModulusLen = keySize / 8
                    PublicExponent = publicExp
                    PrivateData = privateData
                    PrivateLen = keySize / 8
                }
            | None ->
                Error "Unable to compute private exponent"

// PEM output maintaining exact OpenSSL format
let writeRSAKeyPEM (key: SafeRSAKey) (fd: int32) : Result<unit, string> =
    let pemHeader = "-----BEGIN RSA PRIVATE KEY-----\n"
    let pemFooter = "\n-----END RSA PRIVATE KEY-----\n"

    // Encode key data in exact OpenSSL DER format
    match encodeToDER key with
    | Error e -> Error e
    | Ok (derData, derLen) ->
        let base64Data = base64Encode derData derLen
        // Write PEM to file descriptor
        match Fidelity.Libc.IO.write fd pemHeader with
        | Error e -> Error $"Write failed: {e}"
        | Ok _ ->
        match Fidelity.Libc.IO.write fd base64Data with
        | Error e -> Error $"Write failed: {e}"
        | Ok _ ->
        match Fidelity.Libc.IO.write fd pemFooter with
        | Error e -> Error $"Write failed: {e}"
        | Ok _ ->
            // Secure-zero the private key material before returning
            secureZero key.PrivateData key.PrivateLen
            Ok ()

The Many Doors Capability

While the primary innovation is creating drop-in replacements, Farscape offers additional architectural flexibility for libraries with multiple top-level operations. Consider libzip, which handles ZIP archive operations through several distinct functions that each have their own entry point.

For libraries like libzip, Farscape can generate what we call a “many doors” architecture, multiple entry points that can either be compiled into separate tools or combined into a single compatible binary:

# Farscape can analyze libzip and identify distinct operations
farscape generate --type shadow-api --headers zip.h \
                    --style many-doors --output libzip --outputtype single

This generates a project structure with multiple focused entry points:

// libzip/src/main.clef - Multiple entry points for distinct operations
module LibZipSafe

// Individual entry points for specific operations
[<EntryPoint("zip-create")>]
let createMain args =
    // Focused on ZIP creation with type-safe file handling
    match parseCreateArgs args with
    | Ok config -> createZipArchive config
    | Error msg -> eprintfn "%s" msg; 1

[<EntryPoint("zip-extract")>]
let extractMain args =
    // Focused on extraction with bounds checking
    match parseExtractArgs args with
    | Ok config -> extractZipArchive config
    | Error msg -> eprintfn "%s" msg; 1

[<EntryPoint("zip-list")>]
let listMain args =
    // Read-only operations for listing contents
    match parseListArgs args with
    | Ok config -> listZipContents config
    | Error msg -> eprintfn "%s" msg; 1

[<EntryPoint("zip-test")>]
let testMain args =
    // Integrity testing without extraction
    match parseTestArgs args with
    | Ok config -> testZipIntegrity config
    | Error msg -> eprintfn "%s" msg; 1

The many doors architecture provides several benefits for appropriate libraries:

Focused Implementation: Each entry point can be optimized for its specific operation
Selective Verification: SMT proofs can be tailored to the specific safety requirements of each operation
Deployment Flexibility: Organizations can deploy individual tools or the complete compatible binary
Testing Granularity: Each operation can be tested and verified independently

However, the choice of single versus multiple entry points depends entirely on the library’s natural structure. Most tools, like OpenSSL, work perfectly well with a single entry point that maintains complete compatibility with the original interface.

Real-World Impact

The shadow-api approach addresses critical needs in modern infrastructure:

Security Enhancement: Memory safety vulnerabilities in tools like OpenSSL have triggered numerous security incidents. A drop-in replacement could eliminate entire classes of vulnerabilities while maintaining operational continuity.

Gradual Adoption: Organizations can enhance critical tools without the massive coordination required for interface changes. Scripts, automation, and integration tests continue working unchanged.

Verification Capability: F* integration enables mathematical verification of critical operations, providing guarantees that would be extremely challenging with traditional C implementations.

Performance Preservation: Composer’s compilation ensures that safety improvements don’t compromise the performance that organizations depend on. The zero-cost abstraction principle means that all type safety measures, bounds checking, and verification annotations are erased during compilation, producing native code that performs identically to hand-optimized C while providing comprehensive safety guarantees.

Consider a real deployment scenario:

# Current production process (risky but works)
./deploy_certificates.sh  # Uses OpenSSL with memory safety risks

# After Farscape replacement deployment
sudo cp openssl_safe/bin/openssl /usr/bin/openssl

# Same production process (now memory-safe)
./deploy_certificates.sh  # Now uses verified-safe implementation

The deployment is transparent, the interface is identical, but the underlying implementation provides comprehensive safety guarantees.

Expanding the Safe Ecosystem

The shadow-api approach scales across the entire ecosystem of critical C/C++ tools:

Cryptographic Tools: OpenSSL, GnuPG, and similar tools gain memory safety and verification Database Tools: SQLite command-line tools become memory-safe while maintaining compatibility Compression Tools: gzip, tar, and archive utilities gain bounds checking and safe memory management System Tools: Network utilities, file system tools, and system administration commands become safer

Each follows the same pattern: analyze the original tool, generate type-safe Clef implementations, compile to native binaries, run integration tests, review and validate proofs, and deploy as drop-in replacements.

Conclusion

Farscape’s shadow-api mode represents a pragmatic approach to one of software engineering’s most challenging problems: how to enhance the safety of critical infrastructure without disrupting the systems that depend on it. By generating drop-in replacements that maintain perfect compatibility while providing zero-cost safety guarantees, this approach enables organizations to enhance their security posture through gradual, risk-free adoption.

The many doors capability adds architectural flexibility for libraries where multiple entry points provide natural benefits, but the core innovation lies in the ability to create safer versions of the tools we all depend on without changing how we use them.

This shadow-api capability complements Farscape’s standard-lib mode, detailed in “The Farscape Bridge”, by providing a complete spectrum of integration options. Whether embedding C libraries into Fidelity applications or creating safe replacements for system-wide deployment, Farscape bridges the gap between the performance of native code and the safety guarantees that modern computing demands.

As organizations face increasing pressure to eliminate memory safety vulnerabilities from their infrastructure, Farscape provides a path forward that preserves operational continuity while delivering the safety guarantees that critical systems require. The zero-cost abstraction foundation ensures that safety enhancements impose no runtime overhead, maintaining the performance characteristics that make these tools indispensable to modern computing infrastructure.

Ternary Models Vision Intelligent Tree Shaking