zombocoder / bfcfs-linux Public

Notifications You must be signed in to change notification settings
Fork 1
Star 9

Native Linux filesystem for BFC images - mount .bfc read-only via kernel (no FUSE). Fast random I/O, Zstd compression, optional AEAD.

Star

Notifications

zombocoder/bfcfs-linux

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
fs		fs
include		include
.gitignore		.gitignore
BFC_API_REFERENCE.md		BFC_API_REFERENCE.md
Kconfig		Kconfig
Makefile		Makefile
README.md		README.md
dkms.conf		dkms.conf

Repository files navigation

BFCFS - BFC Kernel Filesystem Driver

Build Status License: GPL v2 Kernel Support Status

A native Linux kernel filesystem driver for mounting BFC (Binary File Container) images directly without FUSE.

Features

🚀 Native Performance: Direct kernel integration, no FUSE overhead
📁 Full Directory Support: Complete directory tree navigation and listing
📄 File Reading: Accurate and complete file content access
🔒 Memory Safe: Proper VFS integration with clean resource management
⚡ Direct I/O: Efficient file reading bypassing page cache complications
🛡️ Crash-Free: Stable mount/unmount operations without kernel crashes
🔧 Standard Tools: Works with all standard Linux file utilities (ls, cat, cp, etc.)

Current Status: Phase 0 MVP - ✅ STABLE

The BFCFS kernel module is now fully functional for basic BFC container operations:

✅ Module Loading/Unloading: Clean insertion and removal from kernel
✅ Mount/Unmount Operations: Proper VFS integration without crashes
✅ Directory Operations: Full directory listing and navigation
✅ File Reading: Complete and accurate file content access
✅ Uncompressed Files: Full support for plain (uncompressed, unencrypted) files
✅ VFS Integration: Proper inode allocation and memory management
🚧 Compression: Zstd support planned (Phase 0.2)
🚧 Encryption: AEAD encryption planned (Phase 0.3)

Building

Prerequisites

Important: This filesystem driver requires Linux kernel 6.8.x or newer due to VFS API changes.

# For Ubuntu 22.04, install kernel 6.8.x
sudo apt update
sudo apt install linux-image-6.8.0-49-generic linux-headers-6.8.0-49-generic
sudo reboot
# After reboot, ensure kernel headers are installed
sudo apt install linux-headers-$(uname -r)
# Verify kernel version
uname -r # Should show 6.8.x

Build Commands

# Build the module
make
# Clean build artifacts
make clean
# Load module (for testing)
sudo make load
# Unload module
sudo make unload
# Install to system modules directory
sudo make install

Usage

Quick Start Example

# Load the module
sudo insmod bfcfs.ko
# Mount a BFC container
sudo mount -t bfcfs -o source=/path/to/container.bfc none /mnt/bfc
# Browse contents
ls -la /mnt/bfc/
cat /mnt/bfc/some-file.txt
# Unmount cleanly
sudo umount /mnt/bfc
# Unload module
sudo rmmod bfcfs

Basic Mount (uncompressed containers only)

# Load the module
sudo modprobe bfcfs
# Mount a BFC container
sudo mount -t bfcfs -o source=/path/to/container.bfc /mnt/bfc
# Browse contents
ls -la /mnt/bfc/
# Unmount
sudo umount /mnt/bfc

Mount Options

source=PATH - Path to .bfc container file (required)
verify=MODE - Verification mode: none, shallow, deep (default: shallow)
noreadahead - Disable readahead optimization

Example

sudo mount -t bfcfs -o source=/tmp/app.bfc,verify=deep /mnt/app

Module Signing (Optional)

By default, loading the BFC module will show a "module verification failed" warning and taint the kernel. This is normal for out-of-tree modules but can be avoided by signing the module.

Method 1: Self-Signed Certificate (Recommended)

# Generate signing certificate and private key
openssl req -new -x509 -newkey rsa:2048 -keyout MOK.priv -outform DER -out MOK.der \
 -nodes -days 36500 -subj "/CN=BFC Module/"
# Sign the compiled module
sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha512 MOK.priv MOK.der bfcfs.ko
# Import certificate to Machine Owner Key (MOK) list
sudo mokutil --import MOK.der
# Enter a password when prompted (e.g., "bfcmodule")
# Reboot and enroll the key
sudo reboot

During boot:

UEFI will prompt for MOK enrollment
Select "Enroll MOK" → "Continue"
Enter the password you set above
Reboot to complete enrollment

After enrollment:

# Load the signed module (no more tainted kernel warnings)
sudo insmod bfcfs.ko
# Verify signing status
modinfo bfcfs.ko | grep sig

Method 2: Disable Signature Verification

Alternative approach - add kernel parameter to disable module signature checking:

# Edit GRUB configuration
sudo nano /etc/default/grub
# Add to GRUB_CMDLINE_LINUX_DEFAULT:
GRUB_CMDLINE_LINUX_DEFAULT="... module.sig_enforce=0"
# Update GRUB and reboot
sudo update-grub
sudo reboot

Verification

Check if module is properly signed:

modinfo bfcfs.ko | grep sig
# Should show: sig_id, signer, sig_key, sig_hashalgo, signature

Development

File Structure

bfcfs/
├── include/bfcfs.h # Core data structures and definitions
├── fs/
│ ├── super.c # Superblock and module management
│ ├── opts.c # Mount option parsing
│ ├── index.c # BFC container index parsing
│ ├── inode.c # VFS inode operations
│ ├── data.c # File reading and page cache
│ ├── crypto.c # Encryption support (stub)
│ └── verify.c # Data verification
├── Makefile # Kernel module build
├── Kconfig # Kernel configuration
└── README.md # This file

Testing

# Check if module loaded
lsmod | grep bfcfs
# Check filesystem registration
cat /proc/filesystems | grep bfcfs
# View kernel messages
sudo dmesg | grep bfcfs

Creating Test Containers

Use the BFC CLI tool to create test containers:

# Create uncompressed container
bfc create test.bfc /path/to/source/
# Create with compression (not yet supported by this driver)
bfc create -c zstd test.bfc /path/to/source/

Implementation Phases

Phase 0: Foundation (✅ COMPLETED)

Module infrastructure and VFS registration
Mount option parsing and validation
BFC container format parsing and index loading
Proper VFS inode allocation and memory management
Directory operations (listing, lookup, navigation)
File reading operations with direct I/O
Clean mount/unmount without kernel crashes
Support for uncompressed, unencrypted files
Synthetic root directory handling

Phase 0.2: Compression Support (🚧 Planned)

Zstd decompression integration
Chunked file reading with compression
Performance optimization for compressed files

Phase 0.3: Encryption Support (🚧 Planned)

Kernel keyring integration
ChaCha20-Poly1305 AEAD decryption
Per-chunk encryption/decryption

Phase 1: Advanced Features (🚧 Future)

Symlink support
Extended attributes
Performance optimizations
Advanced verification modes

Contributing

Code Style

Follow Linux kernel coding style
Use scripts/checkpatch.pl to validate patches
Keep functions focused and well-documented

Building Against Different Kernels

Note: Only kernel 6.8.x and newer are supported.

# Build for specific kernel version (6.8.x+ only)
make KERNELDIR=/lib/modules/6.8.0-49/build
# Cross-compile (if toolchain available, 6.8.x+ only)
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

License

GPL v2 - Compatible with Linux kernel licensing

References

About