Skip to content

runtime_paths

Structs

  • RunEntryLayout - Canonical paths within one <runtime>/run/<sandbox_id> entry.
  • RuntimeLayout - Canonical paths rooted at one resolved Firma runtime directory.
  • RuntimeRootInputs - Inputs consulted, in field order, when resolving a runtime root.

Functions

Constants

  • CA_BUNDLE_FILE_NAME - File name of the Sidecar MITM CA appended to the host’s system roots.
  • CA_CERT_FILE_NAME - File name of the Sidecar MITM CA certificate.
  • CA_DIR_NAME - Directory holding the per-run Sidecar HTTPS MITM CA material.
  • CA_KEY_FILE_NAME - File name of the Sidecar MITM CA private key.
  • STATE_DIR_ENV - Environment variable every Firma process resolves its state directory from.

firma_runtime_state::runtime_paths::CA_BUNDLE_FILE_NAME

Section titled “firma_runtime_state::runtime_paths::CA_BUNDLE_FILE_NAME”

Constant: &str

File name of the Sidecar MITM CA appended to the host’s system roots.

firma_runtime_state::runtime_paths::CA_CERT_FILE_NAME

Section titled “firma_runtime_state::runtime_paths::CA_CERT_FILE_NAME”

Constant: &str

File name of the Sidecar MITM CA certificate.

firma_runtime_state::runtime_paths::CA_DIR_NAME

Section titled “firma_runtime_state::runtime_paths::CA_DIR_NAME”

Constant: &str

Directory holding the per-run Sidecar HTTPS MITM CA material.

firma_runtime_state::runtime_paths::CA_KEY_FILE_NAME

Section titled “firma_runtime_state::runtime_paths::CA_KEY_FILE_NAME”

Constant: &str

File name of the Sidecar MITM CA private key.

firma_runtime_state::runtime_paths::RunEntryLayout

Section titled “firma_runtime_state::runtime_paths::RunEntryLayout”

Struct

Canonical paths within one <runtime>/run/<sandbox_id> entry.

This layout models the files shared between the per-run Sidecar producer and runtime-state observers. Component-private files remain with their owning crates.

Methods:

  • fn from_root<impl Into<PathBuf>>(root: impl Trait) -> Self - Construct a run-entry layout from an already resolved root.
  • fn root(self: &Self) -> &Path - Return the run-entry root.
  • fn into_root(self: Self) -> PathBuf - Consume the layout and return its run-entry root.
  • fn sidecar_socket(self: &Self) -> PathBuf - Return the per-run Sidecar Unix socket path.
  • fn sidecar_config(self: &Self) -> PathBuf - Return the generated per-run Sidecar configuration path.
  • fn sidecar_pid(self: &Self) -> PathBuf - Return the per-run Sidecar PID file path.
  • fn sidecar_metadata(self: &Self) -> PathBuf - Return the per-run Sidecar metadata path.
  • fn ca_dir(self: &Self) -> PathBuf - Return the directory holding the per-run Sidecar HTTPS MITM CA.
  • fn ca_cert(self: &Self) -> PathBuf - Return the Sidecar MITM CA certificate.
  • fn ca_bundle(self: &Self) -> PathBuf - Return the Sidecar MITM CA appended to the host’s system roots.
  • fn ca_key(self: &Self) -> PathBuf - Return the Sidecar MITM CA private key.

Traits: Eq

Trait Implementations:

  • Clone
    • fn clone(self: &Self) -> Self
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • PartialEq
    • fn eq(self: &Self, other: &Self) -> bool

firma_runtime_state::runtime_paths::RuntimeLayout

Section titled “firma_runtime_state::runtime_paths::RuntimeLayout”

Struct

Canonical paths rooted at one resolved Firma runtime directory.

Construct this value once at a process boundary and pass it to code that reads or publishes runtime files. This prevents separate operations from resolving environment variables differently.

Methods:

  • fn resolve(flag: Option<PathBuf>) -> Result<Self> - Resolve a runtime layout from an optional explicit root and the process
  • fn from_root<impl Into<PathBuf>>(root: impl Trait) -> Self - Construct a layout from an already resolved runtime root.
  • fn root(self: &Self) -> &Path - Return the resolved runtime root.
  • fn into_root(self: Self) -> PathBuf - Consume the layout and return its runtime root.
  • fn capabilities_dir(self: &Self) -> PathBuf - Return <runtime>/capabilities.
  • fn capability_seed(self: &Self, sandbox_id: &SandboxId) -> PathBuf - Return <runtime>/capabilities/<sandbox_id>.toml.
  • fn run_dir(self: &Self) -> PathBuf - Return <runtime>/run.
  • fn run_entry_layout(self: &Self, sandbox_id: &SandboxId) -> RunEntryLayout - Return the canonical layout for <runtime>/run/<sandbox_id>.
  • fn audit_log(self: &Self) -> PathBuf - Return the default shared audit log path.
  • fn sidecar_socket(self: &Self) -> PathBuf - Return the default long-lived sidecar Unix socket path.
  • fn session_state(self: &Self) -> PathBuf - Return the default persistent enforcement session-state path.
  • fn authority_key(self: &Self) -> PathBuf - Return the default Authority Ed25519 signing-key path.
  • fn authority_public_key(self: &Self) -> PathBuf - Return the default Authority public verification-key path.
  • fn audit_key(self: &Self) -> PathBuf - Return the default audit signing-key path.
  • fn revocations(self: &Self) -> PathBuf - Return the default revocation-list path.
  • fn generated_ca_dir(self: &Self) -> PathBuf - Return the default directory for the Sidecar’s generated HTTPS MITM CA
  • fn generated_ca_cert(self: &Self) -> PathBuf - Return the long-lived Sidecar’s MITM CA certificate.
  • fn generated_ca_bundle(self: &Self) -> PathBuf - Return the long-lived Sidecar’s MITM CA appended to the host’s system
  • fn generated_ca_key(self: &Self) -> PathBuf - Return the long-lived Sidecar’s MITM CA private key.
  • fn tls_dir(self: &Self) -> PathBuf - Return the directory holding Authority TLS material.
  • fn authority_tls_certificate(self: &Self) -> PathBuf - Return the default Authority server TLS certificate path.
  • fn authority_tls_private_key(self: &Self) -> PathBuf - Return the default Authority server TLS private-key path.
  • fn authority_tls_ca_certificate(self: &Self) -> PathBuf - Return the default path of the CA certificate a Sidecar verifies the
  • fn authority_tls_ca_private_key(self: &Self) -> PathBuf - Return the default path of the CA private key that issues Authority TLS

Traits: Eq

Trait Implementations:

  • Clone
    • fn clone(self: &Self) -> Self
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • PartialEq
    • fn eq(self: &Self, other: &Self) -> bool

firma_runtime_state::runtime_paths::RuntimeRootInputs

Section titled “firma_runtime_state::runtime_paths::RuntimeRootInputs”

Struct

Inputs consulted, in field order, when resolving a runtime root.

Every field is an environment value read at a process boundary, so build this from [Default] and set only what the caller actually has:

use firma_runtime_state::runtime_paths::RuntimeRootInputs;
let inputs = RuntimeRootInputs {
firma_state_dir: Some("/var/lib/firma".to_string()),
..RuntimeRootInputs::default()
};

Fields:

  • flag: Option<std::path::PathBuf> - Explicit root supplied on the command line; wins over the environment.
  • firma_state_dir: Option<String> - FIRMA_STATE_DIR.
  • xdg_runtime_dir: Option<String> - XDG_RUNTIME_DIR, used only on Unix.
  • local_app_data: Option<String> - LOCALAPPDATA, used only on Windows.
  • temp: Option<String> - TEMP, used only on Windows.
  • uid: u32 - Effective user id, used only by the Unix /tmp/firma-$UID fallback.

Traits: Eq

Trait Implementations:

  • PartialEq
    • fn eq(self: &Self, other: &Self) -> bool
  • Default
    • fn default() -> Self
  • Clone
    • fn clone(self: &Self) -> Self
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_runtime_state::runtime_paths::STATE_DIR_ENV

Section titled “firma_runtime_state::runtime_paths::STATE_DIR_ENV”

Constant: &str

Environment variable every Firma process resolves its state directory from.

Exported so the processes that set it for a child name the same variable [RuntimeLayout::resolve] reads.

firma_runtime_state::runtime_paths::is_material_present

Section titled “firma_runtime_state::runtime_paths::is_material_present”

Function

Whether the artifact at path is anything other than provably absent.

This is the question every consumer of a state-directory default has to answer before adopting one: firma config writes the material, and a deployment that never generated it must keep its “no anchor configured” behavior instead of failing on a file nobody wrote.

Only a clean NotFound counts as absent. A candidate that exists but cannot be stat-ed — a directory mode that hides it, for instance — is reported as present, so the component that opens it reports the real permission error rather than silently degrading. A directory standing where a file belongs is absent: it is not material anyone can read.

Prefer this over [Path::is_file], which folds both of those cases into “absent”.

fn is_material_present(path: &std::path::Path) -> bool