FSFS - the Fast Secure File System

fast / fæst, fɑst /, adjective:

  1. moving or able to move, operate, function, or take effect quickly; quick; swift; rapid: a fast horse; a fast pain reliever; a fast thinker.
  2. resistant: acid-fast.
  3. closed and made secure, as a door, gate, or shutter.
  4. such as to hold securely: to lay fast hold on a thing.

secure / sɪˈkyʊr /, adjective:

  1. safe from penetration or interception by unauthorized persons: secure radio communications between army units.
  2. affording safety, as a place: he needed a secure hideout.
  3. in safe custody or keeping: here in the vault the necklace was secure.
  4. free from care; without anxiety: emotionally secure.

This is the homepage of FSFS - the Fast Secure File System project.

FSFS is a user space client-server distributed file system that exports encrypted files and directories securely over the network; most of the cryptography is left to the clients, letting users store and retrieve data in a secure, scalable and transparent way. FSFS is written in C, with help from FUSE and OpenSSL; both client and server work on GNU/Linux systems on x86 and PPC architectures, the server also works on Mac OS X 10.3 and above and will be ported to other systems.

The problem

File systems are easily the most evident component of an operating system, from the point of view of users. Through file systems it is possible to organize data in a wide variety of ways, and access resources through a common interface. Users can nowadays not only store and retrieve documents, but also find information on running processes and system settings (through ProcFS), access and manipulate e-mail (for example with GmailFS), or perform several other operations.

In several circumstances and scenarios it is desirable to protect stored files and directories from manipulation by unknown or malicious users: financial or health-related data, confidential documents, or any kind of personal or sensitive data may need to be stored securely, in such a way that it can not be examined or modified freely by third parties. Most file systems do not take action in this sense, and external cryptographic utilities are sometimes employed to secure data before storage. While this can be a perfectly secure solution, it is not transparent for users.

Distributed file systems propose efficient ways of accessing data remotely as if it resided on the local machine; when it comes to dealing with securely stored data as in the examples above, care must be taken to preserve confidentiality and integrity also during network transfer. Not all distributed file systems accomplish this task, weakening the overall security of the system, or do so inefficiently, making it inconvenient for users.

Ideas behind FSFS

FSFS is a secure, distributed file system in users space, written in C with much help from the FUSE and OpenSSL libraries. It lets users store and retrieve data securely and transparently, knowing that it is protected both on permanent storage devices and while in transit over the network. It is also concerned with scalability, therefore separates data cryptography from the server, leaving it to the clients; this approach is similar to the one used in CFS, and opposite to those taken on by other secure file system solutions (like the popular NFS on top of IPsec).

FSFS is written as a pair of user space daemons that act as client and server. Because of this, it needs no kernel support (unlike NFS over IPsec), save the FUSE loadable kernel module on clients, included in Linux since 2.6.14; servers don't use FUSE and depend only on user space OpenSSL libraries.

Servers make use of an existing file system (of virtually any kind) and export a number of directories (currently one, initially empty directory) to clients over the network through two separate channels: a TLS connection set up with OpenSSL, and a clear channel. Requests from the clients to the servers are sent via the TLS socket, thus they are encrypted and authenticated according to TLS v1 specifications by the channel itself, and decrypted on receipt, as they are usually very short and the relevant cryptography does not constitute a great overhead; simple server replies undergo the same process. Cryptography in this case happens at both ends of the transmission.

In a distributed file system, large amounts of data may be transferred between clients and servers, thus encrypting and decrypting everything may become too cumbersome for both parties, and as more clients are added to the system the server may severely lose performance; moreover, sensitive file data should be stored encrypted anyway, so the cryptography could be moved to the clients, in such a way that each encrypts data before a write operation sends it over the network to the server, and decrypts it after a read retrieves it. This way servers only deal with TLS details and can concentrate on serving client requests by doing the relevant I/O on the underlying, "physical" file system. As the data is already encrypted, it does not need to go through the TLS channel and incur the corresponding overhead, but can be sent via the clear channel, provided the messages are authenticated.


FSFS is developed and copyrighted 2005-2007 by Nicola Cocchiaro; all source code is licensed under the GNU General Public License version 2, with the additional exception that linking OpenSSL is allowed.

An excerpt of the GPL license follows:

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
MA  02110-1301, USA.

Latest news

To receive release announcements, project news and other information, subscribe to one of the RSS feeds in the RSS logo RSS feeds page.

Find old news in the old news page.


Project downloads, news and statistics can be found at the SourceForge project page.

Latest code through CVS

You can retrieve the current code snapshot through anonymous CVS (code in CVS is usually more recent and may contain bug fixes, but it can not be guaranteed to be working at all times) using the following commands:

cvs -d:pserver:anonymous@fsfs.cvs.sourceforge.net:/cvsroot/fsfs login
cvs -z3 -d:pserver:anonymous@fsfs.cvs.sourceforge.net:/cvsroot/fsfs co -P fsfs

Alternatively you can browse the web CVS repository; this is also useful to find out module names, in case you don't know them. More information about accessing CVS repositories may be found in the SourceForge document "CVS (Version Control for Source Code)". Updates from within the module's directory do not need the -d parameter.

Stable releases

You can download a stable release from SourceForge, in either source code or pre-built binary package form. The latest release of the FSFS server, client and utilities is 0.1.1; check out the latest release notes and changelog. You can also look at the md5sum file to make sure the package you're downloading is genuine and uncorrupted.

Debian users can also add these lines to their /etc/apt/sources.list file and download the software through their usual package manager:

deb http://cocchiar.web.cs.unibo.it/debian/ unstable main
deb-src http://cocchiar.web.cs.unibo.it/debian/ unstable main


In order to successfully use FSFS, you will need to have certain software installed in your system:

Refer to the respective websites for downloadable packages and installation instructions. Debian binary packakges contain appropriate dependencies for Debian systems.


FSFS uses OpenSSL for all cryptography. Servers need a private 2048-bit (or above) RSA key and identify themselves to clients using public certificates in PEM format; users per default have to identify themselves to servers with similar certificates, but it is not necessary when servers are configured in a way to skip certificate checking (although it's recommended to go with the default setting). The default is to use the OpenSSL AES256-SHA ciphersuite for TLS communication, but client settings can change it at run-time; servers default to the HIGH family of cipersuites (which contains AES-256 and others). Private keys and certificates are only used for TLS connections, so they can be changed at any time, provided the server can verify the correspondence in each pair.

Certificates for each user are produced adding the username to use on the server to the Subject Name; you may refer to the fsfsc-configure script to produce suitable certificate requests. Such username is used during authentication checks and by the server to assume the relevant access privileges to act on the file system on behalf of the user.

File data are encrypted using the AES-256 block cipher in CBC and OFB mode, with 256-bit keys that can be produced using the included fsfsc-configure script (but can be any 256-bit string in theory); file names are stored encrypted with AES-256 in OFB mode. These algorithms may be changed at compile time, but it is then necessary to re-encrypt data in the file system; currently the only way to do so is read all the encrypted data using the old algorithm and copy it to a non-encrypted directory, then rewrite it after switching to the new algorithm. The same goes for users who want to change their symmetric encryption keys.

File data sent through the clear channel are encrypted by the clients before they're sent, and will be stored exactly as they are by the server; the messages themselves are not encrypted but are authenticated using HMAC with SHA-256 as hash function. Session keys are used as input to HMAC, one per direction of transmission, and are computed by the server at the start of each session and sent to the client through the TLS channel.

If a symmetric encryption key is lost there is no way to decrypt encrypted data!


The source code tarballs and binary packages include a README file with instructions on how to set up FSFS and the relevant Certification Authority material if necessary. More documentation, tutorials, and a better web site ;) are coming soon.

Getting started

The fsfsc-configure script can be used on clients to create proper (simple) configuration files for each user interactively, and to generate RSA private keys, certificate requests (that must be signed by a CA) and symmetric encryption keys. The fsfsd-CA script can be used to set up a sample FSFS CA (although any existing CA can in principle be used), sign certificate requests and produce server key/certificate pairs. An example fsfs-openssl.cnf CA configuration file is provided, that is per default installed in /etc/fsfs and helps produce certificates in a way understood by FSFS (PEM format with a specific Subject Name).

All that must be done to start working is launch a server process (fsfsd) on the machine that is going to export data and a client process (fsfsc) on the machine that is going to access that data (may be the same the server runs on), passing them the desired parameters. The client will then mount the exported directory (initially empty, will be populated by the client itself) on the mount point that is passed to it and every access to the file system under that mount point will be directed through FUSE and FSFS. Access permissions are checked in the usual UNIX way, with the additional feature of making interpretation of the exported data virtually impossible without the appropriate encryption key.

Known issues and limitations

FSFS is still in its early stages of development; while the basic functionality is there and it can be used successfully, many features are missing and several improvements can be introduced. A number of them are currently under development, here is a short list of items in random order (more can be found in the TODO file):

Here are some links to similar or generally useful products that have been used during the development of FSFS or have helped its birth with ideas:

Many thanks go also to the following people, in no particular order:

How you can help

There is a lot you can do to help the FSFS project. Proper credit will be given in the software documentation, the changelogs and/or this website. Remember FSFS is released under the GNU General Public License and thus any modifications to the code must be released under the same license.

First and foremost, you can try out the software and send (constructive) comments. Mind the known issues and limitations above! Please be clear and concise in your statements, but feel free to write what you like or dislike, what works and what doesn't, and what's convenient or cumbersome. Improving user experience is an important part of the development of FSFS (again, let the comments be constructive).

If you feel you can improve the main code or the helper scripts, fix bugs, add features or just clean up things, please go ahead and give it a shot. Patches are always welcome and contributions from the community are at the heart of the GNU GPL spirit. Please use something like diff -up to generate patches as it makes it easier both to understand what they do and where they belong, and to apply them.

If you're good at writing documentation, you're welcome to contribute to what will eventually be a sort of user manual containing tutorials and explanations on how FSFS works and how to set it up (to be published on this website and included with the software distribution). Documentation sent should be released under the GNU Free Documentation License (including no invariant parts, please) or a compatible Creative Commons License, and may be edited for consistency and clarity purposes.

If you feel you can improve this website or create a more attractive CSS, if you want to donate money to the project, send gifts or thank-you notes, or contribute in any other way... please don't hesitate to write. Any kind help is always appreciated.

Last but not least... donate to FSFS through SourceForge! Donations to the project help purchasing whatever equipment, software or documentation is needed to further the development or port the software to other systems. They also help pay bills and make developers feel like their work is appreciated, which is always a big aid :) Thank you very much for any help you might provide with donations.


As the GPL license states, FSFS can not be guaranteed to work safely; stable versions are released periodically after being tested, but, as with all software, it obviously can't be assured they will work on all systems or configurations without problems. Therefore it is strongly advised to backup all important data that FSFS acts on. Under no circumstances will the FSFS developers assume any responsibility for any kind of damage, including but not limited to loss of data, security breaches, damage to hardware or software or to any business relying on FSFS. See the full GPL license text for the exact details.

Feel free to contact the FSFS author for questions or contributions:

email address
Last updated: August 11, 2007