A wrapper around Os::File that restricts file access to an allowed directory. More...

#include <Os/SandboxedFile.hpp>

Public Member Functions
	SandboxedFile (const SandboxedFile &)=delete
	Non-copyable (owns file handle) More...

SandboxedFile &	operator= (const SandboxedFile &)=delete
	Non-copy-assignable. More...

	SandboxedFile ()
	Construct a SandboxedFile with default sandbox of `/` More...

	~SandboxedFile ()
	Destroy the SandboxedFile (closes the underlying file if open) More...

void	configure (const char *allowedDirectory)
	Configure the allowed sandbox directory. More...

bool	isConfigured () const
	Check if a sandbox directory has been configured. More...

Os::FileInterface::Status	open (const char *path, Os::FileInterface::Mode mode, Os::FileInterface::OverwriteType overwrite=Os::FileInterface::NO_OVERWRITE)
	Open a file, validating the path against the sandbox directory. More...

void	close ()
	Close the file. More...

bool	isOpen () const
	Check if the file is open. More...

Os::FileInterface::Status	size (FwSizeType &size_result)
	Get size of currently open file. More...

Os::FileInterface::Status	position (FwSizeType &position_result)
	Get file pointer position. More...

Os::FileInterface::Status	preallocate (FwSizeType offset, FwSizeType length)
	Pre-allocate file storage. More...

Os::FileInterface::Status	seek (FwSignedSizeType offset, Os::FileInterface::SeekType seekType)
	Seek file pointer. More...

Os::FileInterface::Status	flush ()
	Flush file contents to storage. More...

Os::FileInterface::Status	read (U8 *buffer, FwSizeType &size, Os::FileInterface::WaitType wait)
	Read data from the file. More...

Os::FileInterface::Status	read (U8 *buffer, FwSizeType &size)
	Read data from the file (blocking, default) More...

Os::FileInterface::Status	write (const U8 *buffer, FwSizeType &size, Os::FileInterface::WaitType wait)
	Write data to the file. More...

Os::FileInterface::Status	write (const U8 *buffer, FwSizeType &size)
	Write data to the file (blocking, default) More...

Os::FileInterface::Status	calculateCrc (U32 &crc)
	Calculate CRC32 of the entire file. More...

const char *	getSandboxDirectory () const
	Get the configured sandbox directory. More...

Detailed Description

A wrapper around Os::File that restricts file access to an allowed directory.

SandboxedFile provides the same interface as Os::File but validates all paths on open() to ensure they resolve to a location within a configured allowed directory. This prevents path-traversal attacks (e.g., ../../etc/shadow) from components that accept externally supplied file paths (such as FileUplink or CFDP receivers).

By default, the sandbox is set to / (root), which allows any absolute path. Call configure() to restrict to a specific directory.

Threat model assumption: untrusted actors cannot create symlinks inside the sandbox. Path validation is purely textual (no realpath() calls) — it does not follow symlinks. On embedded targets without symlink support this is a non-issue. On POSIX targets with untrusted local write access to the sandbox directory, symlink-based escapes are possible; additional measures (e.g., O_NOFOLLOW, realpath() integration) are needed for those deployments.

Usage:

Os::SandboxedFile file;
file.configure("/data/uplink/");
Os::File::Status status = file.open("/data/uplink/mission/seq.bin", Os::File::OPEN_WRITE);
// -> OP_OK
status = file.open("/data/uplink/../../etc/shadow", Os::File::OPEN_WRITE);
// -> NO_PERMISSION

Definition at line 41 of file SandboxedFile.hpp.

Constructor & Destructor Documentation

◆ SandboxedFile() [1/2]

Os::SandboxedFile::SandboxedFile ( const SandboxedFile & )

delete

Non-copyable (owns file handle)

◆ SandboxedFile() [2/2]

Os::SandboxedFile::SandboxedFile ( )

Construct a SandboxedFile with default sandbox of /

The default allows any absolute path. Call configure() to restrict.

Definition at line 12 of file SandboxedFile.cpp.

◆ ~SandboxedFile()

Os::SandboxedFile::~SandboxedFile ( )

Destroy the SandboxedFile (closes the underlying file if open)

Definition at line 14 of file SandboxedFile.cpp.

Member Function Documentation

◆ calculateCrc()

Os::FileInterface::Status Os::SandboxedFile::calculateCrc ( U32 & crc )

Calculate CRC32 of the entire file.

Parameters

crc	output for CRC value

Returns: OP_OK on success

Definition at line 114 of file SandboxedFile.cpp.

◆ close()

void Os::SandboxedFile::close ( )

Close the file.

Definition at line 70 of file SandboxedFile.cpp.

◆ configure()

void Os::SandboxedFile::configure ( const char * allowedDirectory )

Configure the allowed sandbox directory.

Sets the directory that all file operations are restricted to. May be absolute or relative (relative paths are resolved against CWD). A trailing / is appended automatically if not present.

Intended to be called once at startup. Preconditions are enforced with FW_ASSERT: must not be called while a file is open, directory must resolve successfully, must not overflow the buffer.

Parameters

allowedDirectory path of the allowed directory (absolute or relative to CWD)

Definition at line 20 of file SandboxedFile.cpp.

◆ flush()

Os::FileInterface::Status Os::SandboxedFile::flush ( )

Flush file contents to storage.

Returns: OP_OK on success

Definition at line 94 of file SandboxedFile.cpp.

◆ getSandboxDirectory()

const char * Os::SandboxedFile::getSandboxDirectory ( ) const

Get the configured sandbox directory.

Returns: pointer to the sandbox directory string, or nullptr if unconfigured

Definition at line 118 of file SandboxedFile.cpp.

◆ isConfigured()

bool Os::SandboxedFile::isConfigured ( ) const

Check if a sandbox directory has been configured.

Returns: true if configure() has been called successfully

Definition at line 43 of file SandboxedFile.cpp.

◆ isOpen()

bool Os::SandboxedFile::isOpen ( ) const

Check if the file is open.

Returns: true if file is open

Definition at line 74 of file SandboxedFile.cpp.

◆ open()

Os::FileInterface::Status Os::SandboxedFile::open	(	const char *	path,
		Os::FileInterface::Mode	mode,
		Os::FileInterface::OverwriteType	overwrite = `Os::FileInterface::NO_OVERWRITE`
	)

Open a file, validating the path against the sandbox directory.

Resolves the path against CWD and checks containment before opening. Returns NO_PERMISSION if the resolved path falls outside the sandbox.

Parameters

path	c-string path to open
mode	file operation mode
overwrite	overwrite existing file on create

Returns: status of the open (OUTSIDE_SANDBOX if path validation fails)

Definition at line 47 of file SandboxedFile.cpp.

◆ operator=()

SandboxedFile& Os::SandboxedFile::operator= ( const SandboxedFile & )

delete

Non-copy-assignable.

◆ position()

Os::FileInterface::Status Os::SandboxedFile::position ( FwSizeType & position_result )

Get file pointer position.

Parameters

position_result output for position

Returns: OP_OK on success

Definition at line 82 of file SandboxedFile.cpp.

◆ preallocate()

Os::FileInterface::Status Os::SandboxedFile::preallocate	(	FwSizeType	offset,
		FwSizeType	length
	)

Pre-allocate file storage.

Parameters

offset	offset into file
length	length to preallocate

Returns: OP_OK on success

Definition at line 86 of file SandboxedFile.cpp.

◆ read() [1/2]

Os::FileInterface::Status Os::SandboxedFile::read	(	U8 *	buffer,
		FwSizeType &	size,
		Os::FileInterface::WaitType	wait
	)

Read data from the file.

Parameters

buffer	destination buffer
size	bytes to read (updated with actual count)
wait	WAIT or NO_WAIT

Returns: OP_OK on success

Definition at line 98 of file SandboxedFile.cpp.

◆ read() [2/2]

Os::FileInterface::Status Os::SandboxedFile::read	(	U8 *	buffer,
		FwSizeType &	size
	)

Read data from the file (blocking, default)

Parameters

buffer	destination buffer
size	bytes to read (updated with actual count)

Returns: OP_OK on success

Definition at line 102 of file SandboxedFile.cpp.

◆ seek()

Os::FileInterface::Status Os::SandboxedFile::seek	(	FwSignedSizeType	offset,
		Os::FileInterface::SeekType	seekType
	)

Seek file pointer.

Parameters

offset	offset to seek to
seekType	ABSOLUTE or RELATIVE

Returns: OP_OK on success

Definition at line 90 of file SandboxedFile.cpp.

◆ size()

Os::FileInterface::Status Os::SandboxedFile::size ( FwSizeType & size_result )

Get size of currently open file.

Parameters

size_result output for file size

Returns: OP_OK on success

Definition at line 78 of file SandboxedFile.cpp.

◆ write() [1/2]

Os::FileInterface::Status Os::SandboxedFile::write	(	const U8 *	buffer,
		FwSizeType &	size,
		Os::FileInterface::WaitType	wait
	)

Write data to the file.

Parameters

buffer	source buffer
size	bytes to write (updated with actual count)
wait	WAIT or NO_WAIT

Returns: OP_OK on success

Definition at line 106 of file SandboxedFile.cpp.

◆ write() [2/2]

Os::FileInterface::Status Os::SandboxedFile::write	(	const U8 *	buffer,
		FwSizeType &	size
	)

Write data to the file (blocking, default)

Parameters

buffer	source buffer
size	bytes to write (updated with actual count)

Returns: OP_OK on success

Definition at line 110 of file SandboxedFile.cpp.

The documentation for this class was generated from the following files:

Os/SandboxedFile.hpp
Os/SandboxedFile.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SandboxedFile() [1/2]

◆ SandboxedFile() [2/2]

◆ ~SandboxedFile()

Member Function Documentation

◆ calculateCrc()

◆ close()

◆ configure()

◆ flush()

◆ getSandboxDirectory()

◆ isConfigured()

◆ isOpen()

◆ open()

◆ operator=()

◆ position()

◆ preallocate()

◆ read() [1/2]

◆ read() [2/2]

◆ seek()

◆ size()

◆ write() [1/2]

◆ write() [2/2]