Building Privileged Programs
Secure-entry mode is under development. Production qualification is not complete. Internal application.candidate artifacts are explicitly unqualified and must not be installed setuid or used as privileged services. This guide describes the required production contract; the design records the proposed configuration and implementation status.
An optimized ordinary build does not provide this contract. Ordinary AT_SECURE defenses restrict ambient loading when the kernel marks an exec as secure, but an equal-ID root service can start with AT_SECURE=0. Secure-entry enforcement must apply independently of that flag and the IDs.
Supported Boundary
The initial contract supports Linux x86_64 with the pinned static-pie musl toolchain and stock allocator. Dynamic linking, other libc/target choices, custom runtime reuse, instrumentation and application constructors are unsupported. The qualified executable must have full RELRO, verified read-only relocation ranges at runtime, stack protection and stack-clash protection. Flags alone do not establish those properties.
All application modules and the selected entry are compiled into the ELF. There is no runtime compiler, macro expander, evaluator, REPL, bytecode execution, FFI or dynamic module lookup. SIGIL_LIB, -L, adjacent lib/ directories, executable-path changes and appended bundle manifests cannot select code. The ordinary data reader remains available without executable reader extensions. Resources are not embedded through an executable-path archive fallback; applications may authorize explicit data-file access.
Threads, background resolvers and POSIX timer creation are outside this profile. Native dependencies must obey the same restrictions as Sigil code. A C hook or native library is trusted program code and requires source and linked-closure review.
Supported Modules
Secure builds currently admit (sigil core) and (sigil secure-entry), project modules built from them, and local syntax-rules macros. Other standard library modules, including (sigil struct) and (sigil record), are refused at build time. This also affects modules that import them.
Building with an Installed CLI
An installed release CLI can build secure public links. The compiler binary supplies its own core bytecode and proof. Each link stages that pair in a private directory and removes the directory afterward. The staged pair must match the core loaded by the running compiler. Runtime sources come from the project's declared dependencies, and linking uses the pinned Zig toolchain.
Entry and Handoff
The qualified libc/CRT runs before main. Its inventory must identify the permitted TLS, stack-guard, auxv and fixed-device bookkeeping. The prologue does not replace that startup or make an arbitrary toolchain trustworthy.
Before the project hook, the built-in prologue:
- Enforces non-dumpable state and a zero core limit, and protects RELRO.
- Saves all real, effective and saved user/group IDs and the kernel secure observation in a versioned identity structure.
- Discards the ambient environment, blocks signals, disarms all three interval timers, drains inherited pending blockable signals and resets every catchable kernel disposition, including libc-reserved slots.
- Refuses missing startup arguments and repairs closed descriptors 0-2 using
/dev/null. - Calls the optional fixed C hook before Sigil stdio, VM or module initialization.
The hook receives raw argc, argv and envp explicitly. Their presence does not make their contents trusted. Bound their lengths, validate encoding and syntax, and authorize every requested operation before publishing data. The prologue does not impose an application's argument policy.
Pass validated data through the declared typed handoff schema. Each required field is assigned once; missing fields, duplicate assignment, invalid types or bounds, and a nonzero hook result refuse startup. The sealed context is read-only and its Sigil readers return values or fresh copies rather than storage pointers. Do not use environment variables or rewritten argv as a handoff channel.
After the hook, the prologue rechecks protected process state, records hook-period pending signals, seals the context and installs the selected final mask. Hook-selected dispositions remain in effect. The empty mask is the default, so applications that need a different mask must select it explicitly. The runtime then initializes the fixed linked modules and calls the compiled zero-argument entry; it does not select that function through a mutable runtime export lookup.
Explicit final-package static providers initialize after the fixed runtime and before application source units. Their exact original module/cell identities, exports, linked function pointers and arities are checked before entry and on compiled references. They add trusted application C, not arbitrary native dependency loading. See scoped static providers for the manifest and C contracts. Unprivileged mechanism fixtures and a provenance-unverified runtime report do not qualify privileged operation.
The runtime installs no crash dumper or automatic signal handler and reads no implicit tuning or tracing environment. Normal completion releases known resources and exits without dispatching user exit callbacks. Fatal runtime diagnostics are fixed and bounded. Applications remain responsible for redacting their own errors and logs.
Application Responsibilities
The mode establishes a startup and code-loading boundary. The application still owns:
- Authentication, PAM integration, authorization and account policy.
- Credential, supplementary-group, capability, securebits and no-new-privileges decisions, including verification after transitions.
- Paths, ancestor directories, ownership, permissions, symlinks and data parser validation. Linking code into the ELF does not authorize data.
- Existing descriptor policy. Open descriptors 0-2 retain their existing meaning, and caller descriptors above 2 are not silently claimed by the runtime. Check stream access/device policy and define inheritance.
- Session, terminal, working directory, umask and resource-limit policy.
- Secret lifetime, logging, memory safety and trusted native dependencies.
Keep an incompatible libc or PAM integration in a separately qualified native helper. Authorize its executable and construct its child arguments, environment and descriptors explicitly. Clearing the parent's environment does not establish the correct environment for every child role.
The required audited spawn API uses an already-open authorized ELF fd, an immutable bounded plan, atomic pidfd creation and a fixed raw-syscall child trampoline. It accepts no pre-exec callback, shell command, PATH search or ordinary fork fallback. Its public API and qualification remain unfinished; ordinary process APIs are not substitutes for the privileged contract.
Build and Installation Evidence
A production build must emit the executable and its mandatory .secure-entry.json receipt with the module, symbol, startup, runtime-state, context-schema, syscall, closure-test and link-map artifacts. The build must refuse incomplete evidence. These files describe the build; the runtime does not load them as executable startup inputs.
Before privileged installation, the application's verifier must:
- Require its supported schema/profile and exact compiler, toolchain, target, allocator and effective configuration policy.
- Require the expected fixed module/procedure, hook and handoff schema. A built-in-only service is valid only if its own policy permits no hook.
- Recompute the final distributed ELF and every required sidecar digest, and check the reviewed startup and forbidden-capability inventories.
- Require hardening and closure-test results for the intended privilege mode, bound to the same ELF/closure and with detected negative controls.
- Obtain the program's separate deployment authorization.
An ELF header, optimization setting, embedded mode marker or receipt file by itself is insufficient. Receipts cannot make an untrusted compiler, changed native dependency or unsafe application policy trustworthy.
Unprivileged secure-mode tests and link-time forced AT_SECURE decisions cover different paths. Record which technique each test uses. Neither replaces separately authorized real-setuid and root-started VM qualification for the exact distributed artifact. Same-ID libc tests establish wrapper compatibility, not privileged credential transitions. A runtime-wide syscall catalog is advisory; it is not an automatically complete seccomp policy.