composefs-ctl: Add require_signature mount option to varlink Mount/OciMount

Out-of-tree container-lifecycle clients (e.g. composefs-run) want to
request a mount fd and know the kernel actually verified a fs-verity
signature was enrolled on the image, without re-implementing that
check themselves against the repository on the side. Right now the
varlink `Mount`/`OciMount` methods have no way to express that
requirement: a caller can only check signature enrollment out-of-band
and race the mount, or trust the caller of the mount to have done so.

Give `MountParams` an optional `require_signature` field. When set,
`run_mount`/`run_oci_mount` call `has_verity_signature()` on the
freshly-opened image fd before mounting, and refuse with a new
`SignatureRequired` error (added per-interface, so `RepositoryError`
and `OciError` each get their own variant) if the image has fs-verity
enabled but no signature was enrolled. This only checks that *some*
signature exists, matching the kernel's own `.fs-verity` keyring
enforcement at read time; it does not perform certificate-trust
validation, which remains the job of the separate Seal/Sign/Verify
methods.

The field defaults to `None`/unset so existing callers and the wire
format are unaffected.

Adds a real varlink-wire-protocol integration test (a typed OciProxy
client talking to a spawned `cfsctl oci varlink` server over its Unix
socket) covering all three cases: a signed, kernel-enrolled image mounts
successfully with the flag set, an unsigned image is refused with
`SignatureRequired`, and the same unsigned image mounts fine when the
flag is left unset.

Author: cgwalters

crates/composefs-ctl/src/varlink.rs

@@ -129,6 +129,12 @@ pub enum RepositoryError {
         /// The ref name that was not found.
         reference: String,
     },
+    /// `require_signature` was requested but the underlying image has no
+    /// kernel-enrolled fs-verity signature.
+    SignatureRequired {
+        /// The name/selector that was requested to be mounted.
+        name: String,
+    },
     /// An unexpected internal error occurred while servicing the request.
     InternalError {
         /// Description of the failure.
@@ -460,6 +466,16 @@ pub struct MountParams {
     pub overlay: Option<bool>,
     /// Whether to mount read-write (only meaningful with overlay).
     pub read_write: Option<bool>,
+    /// When `true`, require that the underlying EROFS image has a kernel
+    /// fs-verity signature enrolled (i.e. a signature was successfully
+    /// registered via `FS_IOC_ENABLE_VERITY` at pull/import time — see
+    /// `has_verity_signature()`). If the image has verity enabled but no
+    /// enrolled signature, the mount is refused. This does NOT perform any
+    /// certificate-trust validation (see the separate Seal/Sign/Verify
+    /// varlink methods for that) — it only confirms *some* signature was
+    /// enrolled and is therefore subject to the kernel's own enforcement
+    /// via `.fs-verity` keyring lookups at read time.
+    pub require_signature: Option<bool>,
 }
 
 impl MountParams {
@@ -504,12 +520,45 @@ pub struct MountReply {
     pub fd_index: u32,
 }
 
+/// Check whether `name`'s underlying image has a kernel-enrolled fs-verity
+/// signature, for [`MountParams::require_signature`].
+///
+/// Opens the image fd fresh via [`Repository::open_image`] rather than
+/// threading through the fd that `mount_with_options` will open again
+/// internally: this is a cheap read-only open of a file that's immutable
+/// once fs-verity is enabled, and keeps this varlink-layer policy check out
+/// of the core `Repository` API.
+fn image_has_verity_signature<ObjectID: FsVerityHashValue>(
+    repo: &Repository<ObjectID>,
+    name: &str,
+) -> anyhow::Result<bool> {
+    let (fd, _enable_verity) = repo.open_image(name)?;
+    composefs::fsverity::has_verity_signature(&fd)
+        .context("Checking kernel fs-verity signature enrollment")
+}
+
 fn run_mount<ObjectID: FsVerityHashValue>(
     repo: &Repository<ObjectID>,
     name: &str,
     params: &MountParams,
     fds: Vec<std::os::fd::OwnedFd>,
 ) -> std::result::Result<(MountReply, Vec<std::os::fd::OwnedFd>), RepositoryError> {
+    if params.require_signature.unwrap_or(false) {
+        match image_has_verity_signature(repo, name) {
+            Ok(true) => {}
+            Ok(false) => {
+                return Err(RepositoryError::SignatureRequired {
+                    name: name.to_string(),
+                });
+            }
+            Err(e) => {
+                return Err(RepositoryError::InternalError {
+                    message: format!("Checking fs-verity signature enrollment: {e:#}"),
+                });
+            }
+        }
+    }
+
     let options = params.to_mount_options(fds)?;
 
     let mount_fd =
@@ -555,6 +604,22 @@ fn run_oci_mount<ObjectID: composefs::fsverity::FsVerityHashValue>(
         },
     })?;
 
+    if params.require_signature.unwrap_or(false) {
+        match image_has_verity_signature(repo, &erofs_id.to_hex()) {
+            Ok(true) => {}
+            Ok(false) => {
+                return Err(oci::OciError::SignatureRequired {
+                    image: image.to_string(),
+                });
+            }
+            Err(e) => {
+                return Err(oci::OciError::InternalError {
+                    message: format!("Checking fs-verity signature enrollment: {e:#}"),
+                });
+            }
+        }
+    }
+
     let options = params
         .to_mount_options(fds)
         .map_err(|e| oci::OciError::InternalError {
@@ -1058,7 +1123,9 @@ mod service_impl {
         ///
         /// If overlay upper/work directories are needed, pass them as two fds
         /// (upperdir, workdir) via SCM_RIGHTS. The returned fd is a detached
-        /// mount that the caller can attach with `move_mount()`.
+        /// mount that the caller can attach with `move_mount()`. If
+        /// `options.require_signature` is `true`, the mount is refused unless
+        /// the underlying image has a kernel-enrolled fs-verity signature.
         #[zlink(return_fds)]
         async fn mount(
             &self,
@@ -1228,7 +1295,9 @@ mod service_impl {
         ///
         /// If overlay upper/work directories are needed, pass them as two fds
         /// (upperdir, workdir) via SCM_RIGHTS. The returned fd is a detached
-        /// mount that the caller can attach with `move_mount()`.
+        /// mount that the caller can attach with `move_mount()`. If
+        /// `options.require_signature` is `true`, the mount is refused unless
+        /// the underlying image has a kernel-enrolled fs-verity signature.
         #[zlink(return_fds)]
         async fn mount(
             &self,
@@ -1457,7 +1526,9 @@ mod service_impl {
         /// Resolves the image by ref name or `sha256:` digest, finds its
         /// EROFS image (or boot variant if `bootable` is true), and creates
         /// a composefs mount. If `options.overlay` is true, the fd array
-        /// must contain upperdir and workdir fds.
+        /// must contain upperdir and workdir fds. If `options.require_signature`
+        /// is `true`, the mount is refused unless the resolved EROFS image has
+        /// a kernel-enrolled fs-verity signature.
         #[zlink(interface = "org.composefs.Oci", return_fds)]
         async fn oci_mount(
             &self,
@@ -2180,6 +2251,12 @@ pub mod oci {
             /// Description of the failure.
             message: String,
         },
+        /// `require_signature` was requested but the underlying image has no
+        /// kernel-enrolled fs-verity signature.
+        SignatureRequired {
+            /// The image reference that lacks an enrolled signature.
+            image: String,
+        },
         /// An unexpected internal error occurred while servicing the request.
         InternalError {
             /// Description of the failure.
@@ -2199,6 +2276,9 @@ pub mod oci {
                 OciError::SignatureVerificationFailed { message } => {
                     write!(f, "SignatureVerificationFailed: {message}")
                 }
+                OciError::SignatureRequired { image } => {
+                    write!(f, "SignatureRequired: {image}")
+                }
                 OciError::InternalError { message } => write!(f, "InternalError: {message}"),
             }
         }
@@ -2223,6 +2303,8 @@ pub mod proxy {
         RepositoryError,
     };
     #[cfg(feature = "oci")]
+    use super::{MountParams, MountReply};
+    #[cfg(feature = "oci")]
     use zlink::futures_util::Stream;
 
     /// Typed client for the `org.composefs.Repository` interface.
@@ -2345,6 +2427,17 @@ pub mod proxy {
             cert_pem: Option<&str>,
         ) -> zlink::Result<Result<VerifyReply, OciError>>;
 
+        /// Mount an OCI image and return the detached mount fd.
+        #[zlink(return_fds)]
+        async fn oci_mount(
+            &mut self,
+            handle: u64,
+            image: &str,
+            bootable: bool,
+            options: MountParams,
+            #[zlink(fds)] fds: Vec<std::os::fd::OwnedFd>,
+        ) -> zlink::Result<(Result<MountReply, OciError>, Vec<std::os::fd::OwnedFd>)>;
+
         /// Pull an OCI image, streaming progress frames.
         #[zlink(more, rename = "Pull")]
         async fn pull(

crates/composefs-integration-tests/src/tests/privileged.rs

@@ -1529,6 +1529,176 @@ fn privileged_varlink_kernel_sig_no_cert() -> Result<()> {
 }
 integration_test!(privileged_varlink_kernel_sig_no_cert);
 
+/// Attaches a detached mount fd (as returned by the `OciMount`/`Mount`
+/// varlink methods) at a fresh temporary directory, and detaches it again
+/// on drop so the test doesn't leak mounts.
+struct AttachedMount {
+    dir: tempfile::TempDir,
+}
+
+impl AttachedMount {
+    fn new(fs_fd: std::os::fd::OwnedFd) -> Result<Self> {
+        let dir = tempfile::tempdir()?;
+        composefs_oci::composefs::mount::mount_at(fs_fd, rustix::fs::CWD, dir.path())
+            .context("Attaching detached mount fd")?;
+        Ok(Self { dir })
+    }
+
+    fn path(&self) -> &Path {
+        self.dir.path()
+    }
+}
+
+impl Drop for AttachedMount {
+    fn drop(&mut self) {
+        let _ = rustix::mount::unmount(self.dir.path(), rustix::mount::UnmountFlags::DETACH);
+    }
+}
+
+/// Extract the fd at `index` from a `return_fds` reply's fd vector.
+fn take_fd(mut fds: Vec<std::os::fd::OwnedFd>, index: u32) -> Result<std::os::fd::OwnedFd> {
+    let index = index as usize;
+    ensure!(
+        index < fds.len(),
+        "fd_index {index} out of range ({} fds returned)",
+        fds.len()
+    );
+    Ok(fds.remove(index))
+}
+
+/// `OciMount`'s `require_signature` option: mounting a kernel-signature-
+/// enrolled image with the flag set succeeds and yields a real, working
+/// mount; mounting an unsigned image with the same flag is refused with
+/// `SignatureRequired`; and the flag is opt-in — the unsigned image mounts
+/// fine when it's left unset.
+///
+/// This is the varlink-layer building block for out-of-tree
+/// container-lifecycle clients (e.g. composefs-run) that want "only give me
+/// a mount if the kernel actually verified a fs-verity signature was
+/// enrolled" without re-implementing that check themselves on top of the
+/// existing `Mount`/`OciMount` methods.
+fn privileged_varlink_require_signature() -> Result<()> {
+    if require_privileged("privileged_varlink_require_signature")?.is_some() {
+        return Ok(());
+    }
+    if !fsverity_keyring_exists()? {
+        println!(
+            "SKIP: kernel lacks CONFIG_FS_VERITY_BUILTIN_SIGNATURES support (.fs-verity keyring not found)"
+        );
+        return Ok(());
+    }
+
+    let sh = Shell::new()?;
+    let cfsctl_bin = cfsctl()?;
+    let fixture_dir = tempfile::tempdir()?;
+
+    let (cert_pem, key_pem) = composefs_oci::signing::generate_test_keypair();
+    let cert_path = fixture_dir.path().join("cert.pem");
+    let key_path = fixture_dir.path().join("key.pem");
+    std::fs::write(&cert_path, &cert_pem)?;
+    std::fs::write(&key_path, &key_pem)?;
+
+    // A real signed-and-enrolled image, and a plain image that was never
+    // signed at all (so it can never get a kernel signature regardless of
+    // keyring state).
+    let signed_layout =
+        build_signed_oci_layout(&sh, &cfsctl_bin, fixture_dir.path(), &cert_path, &key_path)?;
+    let unsigned_layout = create_oci_layout(fixture_dir.path())?;
+
+    cmd!(sh, "{cfsctl_bin} keyring add-cert {cert_path}").read()?;
+
+    let verity_dir = VerityTempDir::new()?;
+    let repo = verity_dir.path().join("repo");
+    cmd!(sh, "{cfsctl_bin} --repo {repo} init").run()?;
+
+    let svc = VarlinkService::oci(&repo)?;
+
+    svc.proxy_pull(
+        &format!("oci:{}", signed_layout.display()),
+        Some("signed-image"),
+        false,
+    )
+    .context("Pull (signed) transport error")?
+    .map_err(|e| anyhow::anyhow!("Pull of signed image should succeed: {e:?}"))?;
+    ensure!(
+        image_has_verity_signature(&svc, &repo, "signed-image")?,
+        "expected the kernel to have enrolled the signature on the signed image"
+    );
+
+    svc.proxy_pull(
+        &format!("oci:{}", unsigned_layout.display()),
+        Some("unsigned-image"),
+        false,
+    )
+    .context("Pull (unsigned) transport error")?
+    .map_err(|e| anyhow::anyhow!("Pull of unsigned image should succeed: {e:?}"))?;
+    ensure!(
+        !image_has_verity_signature(&svc, &repo, "unsigned-image")?,
+        "expected no signature to be enrolled on the never-signed image"
+    );
+
+    // Attaches a successful OciMount reply and checks it's a real, working
+    // mount of the shared `hello.txt` fixture (see `create_oci_layout`).
+    const HELLO_CONTENTS: &str = "hello from test layer\n";
+    let assert_mount_works =
+        |reply: composefs_ctl::varlink::MountReply, fds: Vec<std::os::fd::OwnedFd>| -> Result<()> {
+            let mount = AttachedMount::new(take_fd(fds, reply.fd_index)?)?;
+            let hello = std::fs::read_to_string(mount.path().join("hello.txt"))?;
+            ensure!(
+                hello == HELLO_CONTENTS,
+                "unexpected mounted file content: {hello:?}"
+            );
+            Ok(())
+        };
+
+    // `require_signature: true` on the signed image succeeds and yields a
+    // real, working mount.
+    {
+        let (result, fds) = svc
+            .proxy_oci_mount("signed-image", false, Some(true))
+            .context("OciMount (signed, required) transport error")?;
+        let reply = result.map_err(|e| {
+            anyhow::anyhow!(
+                "OciMount with require_signature on a signed image should succeed: {e:?}"
+            )
+        })?;
+        assert_mount_works(reply, fds)?;
+    }
+
+    // `require_signature: true` on the unsigned image must be refused with
+    // the specific `SignatureRequired` error, not just any error.
+    {
+        let (result, fds) = svc
+            .proxy_oci_mount("unsigned-image", false, Some(true))
+            .context("OciMount (unsigned, required) transport error")?;
+        ensure!(fds.is_empty(), "expected no fds on a refused mount");
+        match result {
+            Err(composefs_ctl::varlink::oci::OciError::SignatureRequired { image }) => {
+                ensure!(
+                    image == "unsigned-image",
+                    "unexpected image in SignatureRequired: {image}"
+                );
+            }
+            other => bail!("expected OciError::SignatureRequired, got: {other:?}"),
+        }
+    }
+
+    // `require_signature` is opt-in: leaving it unset still mounts the
+    // unsigned image successfully.
+    {
+        let (result, fds) = svc
+            .proxy_oci_mount("unsigned-image", false, None)
+            .context("OciMount (unsigned, not required) transport error")?;
+        let reply = result.map_err(|e| {
+            anyhow::anyhow!("OciMount without require_signature should succeed: {e:?}")
+        })?;
+        assert_mount_works(reply, fds)?;
+    }
+
+    Ok(())
+}
+integration_test!(privileged_varlink_require_signature);
+
 /// `cfsctl keyring add-cert` on its own, independent of any OCI pull flow.
 /// Branches on kernel support rather than skipping, since both outcomes
 /// (success, or a clear `KeyringNotFound` error) are meaningful and worth