DOCSEARCHbyAlgolia
Submit Docs

securefs Documentation

repository·master·Indexed 21 days ago

https://github.com/netheril96/securefs

A FUSE-based filesystem providing transparent, authenticated, and probabilistic encryption for files and directories. It features two storage modes: a 'lite' format optimized for cloud synchronization and a 'full' format that flattens directory structures into B-trees for higher security. Supports cross-platform usage on Windows, Linux, FreeBSD, and macOS, with features including AES256-GCM encryption, AES-SIV filename encryption, and configurable key derivation via argon2id, scrypt, or pbkdf2-hmac.

Tokens
3.9K
Snippets
13
Records
21
Agent score
74%

What's inside securefs

  1. Understand the securefs Full Format (Versions 1, 2, 3)

    master

    The Full Format is designed for high security and randomized encryption.

    Key characteristics:

    • Identity: Every file, directory, or symlink is identified by a 256-bit ID generated by a CSPRNG. The root directory always has an ID of zero.
    • Storage Model: Uses a pair of files in the underlying filesystem for every virtual file. The structure is similar to a git object store.
    • Encryption: Data is divided into 4KiB blocks. Each block is separately encrypted and authenticated using AES256-GCM. A new IV/nonce is generated via CSPRNG for every block modification.
    • Metadata: IVs and MACs are stored in an associated meta file. The meta file's integrity is protected by a leading HMAC-SHA256 of its remaining contents.
    • Directory Implementation: Directories are implemented as normal files containing a B-tree rather than using the underlying filesystem's directory structure. This allows for randomized encryption while maintaining logarithmic access complexity ($O(\log n)$). The maximum filename length is 255.
    • Version Differences:
      • v1: Original format.
      • v2 & v3: Use less paranoid parameters than v1.
      • v3: Stores timestamps in the meta file (instead of relying on the underlying filesystem) to facilitate synchronization across cloud services.

  2. How extended attributes (xattr) are handled

    master

    securefs supports extended attributes (xattr) if the underlying filesystem does, but the implementation details vary by format and OS.

    General Rules:

    • Names: The names of xattrs are not encrypted to ensure cross-platform compatibility and avoid filesystem restrictions.
    • Disabling: Users can disable xattr processing during the mounting process.

    Format Specifics:

    • Full Format: Uses a separate key for xattr encryption.
    • Lite Format (v4): Only the values of the xattrs are encrypted using AES-GCM. A separate key is used for xattr encryption to prevent security weaknesses in xattr handling from affecting the rest of the system.
    • macOS Specifics:
      • On macOS, securefs will never set com.apple.FinderInfo or com.apple.quarantine to avoid OS-level bugs.
      • Lite format supports xattr specifically to ensure compatibility with macOS applications.

  3. Understand Lite vs Full filesystem formats

    master

    securefs provides two distinct filesystem formats that change how data is stored on the underlying disk:

    Lite Format (Default)

    • Mechanism: Encrypts filenames and file contents separately.
    • Pros: Faster performance; easier conflict resolution for cloud sync services (Dropbox, Google Drive, etc.).
    • Cons: Less information hiding regarding the filesystem hierarchy compared to Full mode.

    Full Format

    • Mechanism: Maps files, directories, and symlinks in the virtual filesystem to regular files in the underlying filesystem. The directory structure is flattened and recorded as B-trees within these files.
    • Pros: Higher security; leaks less information about the filesystem hierarchy; runs independently of the underlying filesystem's features.
    • Cons: Slower than Lite mode.
    • Activation: Must be requested via securefs create --format full.

  4. Understand filename length limits in lite format

    master

    In securefs lite format, filenames are encrypted using AES-SIV and then converted via Base32. This expansion means that a filename of 143 bytes will result in a 255-byte filename. If a filename exceeds this limit, it will exceed the maximum length supported by most filesystems.

    To handle this, securefs (version 1.0.0+) uses a long name support feature:

    1. When a filename exceeds a threshold (default: 128 bytes), it is transformed into an underlying filename using Base32(Blake2b(name_master_key, filename)) followed by three dots.
    2. The original AES-SIV encrypted name and this transformed name are stored in a per-directory SQLite database.
    3. The database is queried during ls calls and updated during file creation, deletion, or movement.

    Note that this approach incurs a performance penalty due to the SQLite database lookups.

  5. How securefs handles file and directory names

    master

    To prevent filename leakage while maintaining performance, securefs uses deterministic authenticated encryption (AES-SIV per RFC 5297) for names.

    Implications for users:

    • Privacy: Filenames cannot be deduced, but identical filenames in the virtual filesystem will result in identical encrypted names in the underlying filesystem.
    • Encoding: Encrypted names are converted to Base32 (DUDE alphabet, no padding) to ensure compatibility with case-insensitive filesystems. Base64 is avoided for this reason.
    • Filename Length: Because of the IV and Base32 encoding, the underlying filename is longer than the virtual filename. Consequently, the maximum filename length in the mounted filesystem is always shorter than the underlying filesystem's limit.

  6. Understand the securefs Lite Format (Version 4)

    master

    The Lite Format (Version 4) is optimized for different use cases, prioritizing file-level storage over the meta-file approach.

    Key characteristics:

    • File Structure: Instead of a separate meta file, the IV is prepended and the tag is appended directly to the ciphertext within the underlying file.
    • Key Derivation: Each file starts with a 16-byte random block. This block is encrypted by the master content key (256 bits) using AES to derive a unique 128-bit file-specific key.
    • Block Security: Blocks are encrypted with AES-GCM. The block number is included as associated data in the AES-GCM call, preventing blocks from being moved within or across files without detection.
    • Limitations:
      • An attacker may replace a file block with an older version of the same block at the same position without triggering a security failure.
      • File sizes are limited to $2^{31} - 1$ blocks (approx. 8TiB for 4KiB blocks) to comply with NIST recommendations regarding IV usage.
    • Sparse Files: All-zero blocks are passed through to support sparse files efficiently.

  7. Mount a secure filesystem with securefs mount

    master

    Once a directory is created, use the mount command (or m) to attach it to a mount point. The mount point will act as a regular filesystem where you can read and write files transparently.

    Usage Examples

    • Standard mount: securefs mount ~/Secret ~/Mount (Press Ctrl-C to unmount).
    • Mount with keyfile: securefs mount ~/Secret ~/Mount --keyfile ./mykey.
    • Background mount (Linux/macOS only): securefs m -b ~/Secret ~/Mount --log ~/securefs.log (Use umount to unmount).
    • Do not encrypt filenames: securefs m --plain-text-names ~/Secret ~/Mount.
    • Windows specific mount: securefs m ~/Secret Z:
    securefs mount ~/Secret ~/Mount
securefs m -b ~/Secret ~/Mount --log ~/securefs.log

  8. Create a new securefs filesystem

    master

    Use the create (or c) subcommand to initialize a new encrypted directory. You must specify the directory where the encrypted data will be stored.

    Repository Formats

    • lite (default): Faster and more reliable. The directory structure is visible, but filenames exceeding --long-name-threshold (default 128 bytes) are stored encrypted in a SQLite database.
    • full: Offers higher privacy by encrypting the directory structure, but comes with performance and synchronization trade-offs.

    Security Options

    • --pass: Provide a password. It is recommended to type this manually or pipe it for better security.
    • --keyfile: Provide an optional path to a key file. This can be used with or instead of a password.
    • --askpass: A switch that forces a password prompt even if a --keyfile is provided. Using both password and keyfile provides stronger security.
    • Argon2 Parameters: You can tune the key derivation using --argon2-t (time cost, default 30), --argon2-m (memory cost in KiB, default 262144), and --argon2-p (parallelism, default 4).
    # Create a lite filesystem in the 'my_data' directory
securefs create my_data

# Create a full format filesystem with a keyfile and password prompt
securefs create my_data --format full --keyfile ./my.key --askpass

  9. Migrate lite format repositories to support long filenames

    master

    Lite format repositories created before securefs 1.0.0 do not support long filenames. You can enable this support by running the migration command.

    Important Constraints:

    • Migration can only be performed if the repository does not contain any symbolic links, as the encryption method for symbolic links changed with the introduction of long name support.
    securefs migrate-long-name

  11. Mount an existing securefs filesystem

    master

    Use the mount (or m) subcommand to attach an existing encrypted directory to a mount point. You must provide both the source directory containing the data and the target mount point.

    Key Options

    • --config: Path to the config file. Defaults to ${data_dir}/.config.pb.
    • --pass / --keyfile / --askpass: Authentication methods (see create for details).
    • -b or --background: Spawns a child process to mount in the background (supported on Windows).
    • -s or --single: Enables single-threaded mode.
    • -i or --insecure: Disables all integrity verification.
    • -x or --noxattr: Disables built-in xattr support.
    • -v or --verbose: Enables verbose logging.
    • --max-idle-seconds: Automatically unmounts the filesystem after N seconds of inactivity (default 0, no auto-unmount).
    • -o or --opt: Pass additional FUSE options. Warning: This may crash the filesystem; use only for testing.
    # Mount the encrypted data in 'my_data' to the directory 'my_mount'
securefs mount my_data my_mount

# Mount in the background with verbose logging
securefs mount my_data my_mount -b -v

  12. Change the password or keyfile of a filesystem

    master

    Use the chpass subcommand to update the authentication credentials for an existing filesystem.

    Usage

    You must provide the directory containing the data. You can provide the old credentials via --oldpass or --oldkeyfile and the new credentials via --newpass or --newkeyfile.

    To increase security, use --askoldpass or --asknewpass to force manual password entry even if a keyfile is used.

    # Change password for the filesystem in 'my_data'
securefs chpass my_data --oldpass OLD_PASSWORD --newpass NEW_PASSWORD