Struct SealOptions

pub struct SealOptions<'a> { /* private fields */ }

Options for creating a sealed anonymous file.

Implementations

impl<'a> SealOptions<'a>

pub const fn new() -> SealOptions<'a>

Create a default set of options ready for configuration.

This is equivalent to:

SealOptions::new()
    .close_on_exec(true)
    .memfd_name(c"pentacle_sealed")
    .must_seal_seals(true)
    .must_seal_shrinking(true)
    .must_seal_growing(true)
    .must_seal_writing(true)
    .seal_future_writing(false)
    .seal_executable(false);

pub const fn close_on_exec(self, close_on_exec: bool) -> SealOptions<'a>

Sets the close-on-exec (CLOEXEC) flag for the new file.

When a child process is created, the child normally inherits any open file descriptors. Setting the close-on-exec flag will cause this file descriptor to automatically be closed instead.

This flag is true by default, matching the behavior of std::fs.

pub const fn executable(self, executable: bool) -> SealOptions<'a>

Sets whether the resulting file must have or not have execute permission set.

If set, the OS is explicitly asked to set the execute permission when exec is true, or unset the execute permission when exec is false. If the OS refuses, SealOptions::create tries to set or unset the execute permission, and returns an error if it fails.

Calling this function enables the equivalent of calling SealOptions::seal_executable with true for implementation reasons.

This flag is neither true nor false by default; instead behavior is delegated to the OS’s default behavior.

Context

The original memfd_create(2) implementation on Linux creates anonymous files with the executable permission set. Later in Linux 6.3, programs and system administrators were given tools to control this (see also https://lwn.net/Articles/918106/):

• Setting the sysctl vm.memfd_noexec = 1 disables creating executable anonymous files unless the program requests it with MFD_EXEC (set by pentacle if executable is true).
• Setting the sysctl vm.memfd_noexec = 2 disables the ability to create executable anonymous files altogether, and MFD_NOEXEC_SEAL must be used (set by pentacle if executable is false).
• Calling memfd_create(2) with MFD_NOEXEC_SEAL enables the F_SEAL_EXEC seal.

Linux prior to 6.3 is unaware of MFD_EXEC and F_SEAL_EXEC. If memfd_create(2) sets errno to EINVAL, this library retries the call without possibly-unknown flags, and the permission bits of the memfd are adjusted depending on this setting.

pub const fn memfd_name(self, name: &'a CStr) -> SealOptions<'a>

Set a name for the file for debugging purposes.

On Linux, this name is displayed as the target of the symlink in /proc/self/fd/.

The default name is pentacle_sealed.

pub const fn seal_seals(self, seal_seals: bool) -> SealOptions<'a>

If true, try to prevent further seals from being set on this file.

If false, also set SealOptions::must_seal_seals to false.

This flag is true by default.

pub const fn must_seal_seals(self, must_seal_seals: bool) -> SealOptions<'a>

If true, also set SealOptions::seal_seals to true and ensure it is successful when SealOptions::seal is called.

This flag is true by default.

pub const fn seal_shrinking(self, seal_shrinking: bool) -> SealOptions<'a>

If true, try to prevent shrinking this file.

If false, also set SealOptions::must_seal_shrinking to false.

This flag is true by default.

pub const fn must_seal_shrinking( self, must_seal_shrinking: bool, ) -> SealOptions<'a>

If true, also set SealOptions::seal_shrinking to true and ensure it is successful when SealOptions::seal is called.

This flag is true by default.

pub const fn seal_growing(self, seal_growing: bool) -> SealOptions<'a>

If true, try to prevent growing this file.

If false, also set SealOptions::must_seal_growing to false.

This flag is true by default.

pub const fn must_seal_growing(self, must_seal_growing: bool) -> SealOptions<'a>

If true, also set SealOptions::seal_growing to true and ensure it is successful when SealOptions::seal is called.

This flag is true by default.

pub const fn seal_writing(self, seal_writing: bool) -> SealOptions<'a>

If true, try to prevent writing to this file.

If false, also set SealOptions::must_seal_writing to false.

This flag is true by default.

pub const fn must_seal_writing(self, must_seal_writing: bool) -> SealOptions<'a>

If true, also set SealOptions::seal_writing to true and ensure it is successful when SealOptions::seal is called.

This flag is true by default.

pub const fn seal_future_writing( self, seal_future_writing: bool, ) -> SealOptions<'a>

If true, try to prevent directly writing to this file or creating new writable mappings, but allow writes to existing writable mappings.

If false, also set SealOptions::must_seal_future_writing to false.

This flag is false by default.

This requires at least Linux 5.1.

pub const fn must_seal_future_writing( self, must_seal_future_writing: bool, ) -> SealOptions<'a>

If true, also set SealOptions::seal_future_writing to true and ensure it is successful when SealOptions::seal is called.

This flag is false by default.

This requires at least Linux 5.1.

pub const fn seal_executable(self, seal_executable: bool) -> SealOptions<'a>

If true, try to prevent modifying the executable permission of the file.

If false, also set SealOptions::must_seal_executable to false.

This flag is false by default.

If SealOptions::executable has already been called, this function does nothing, apart from setting SealOptions::must_seal_executable to false if seal_executable is false.

This requires at least Linux 6.3.

pub const fn must_seal_executable( self, must_seal_executable: bool, ) -> SealOptions<'a>

If true, also set SealOptions::seal_executable to true and ensure it is successful when SealOptions::seal is called.

This flag is false by default.

This requires at least Linux 6.3.

pub fn copy_and_seal<R: Read>(&self, reader: &mut R) -> Result<File, Error>

Create an anonymous file, copy the contents of reader to it, and seal it.

This is equivalent to:

let mut file = options.create()?;
std::io::copy(reader, &mut file)?;
options.seal(&mut file)?;

Errors

This method returns an error when any of SealOptions::create, std::io::copy, or SealOptions::seal fail.

pub fn create(&self) -> Result<File, Error>

Create an unsealed anonymous file with these options.

It is the caller’s responsibility to seal this file after writing with SealOptions::seal. If possible, avoid using this function and prefer SealOptions::copy_and_seal.

Errors

This method returns an error when:

• memfd_create(2) fails
• SealOptions::executable was set but permissions cannot be changed as required

pub fn seal(&self, file: &mut File) -> Result<(), Error>

Seal an anonymous file with these options.

This should be called on a file created with SealOptions::create. Attempting to use this method on other files will likely fail.

Errors

This method returns an error when:

• the fcntl(2) F_ADD_SEALS command fails (other than EINVAL)
• the fcntl(2) F_GET_SEALS command fails
• if any required seals are not present (in this case, Error::source will be MustSealError)

pub fn is_sealed(&self, file: &File) -> bool

Check if file is sealed as required by these options.

If the file doesn’t support sealing (or fcntl(2) otherwise returns an error), this method returns false.

Trait Implementations

impl<'a> Clone for SealOptions<'a>

fn clone(&self) -> SealOptions<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for SealOptions<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for SealOptions<'a>

fn default() -> SealOptions<'a>

Returns the “default value” for a type.

impl<'a> PartialEq for SealOptions<'a>

fn eq(&self, other: &SealOptions<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> StructuralPartialEq for SealOptions<'a>