PhoneBook Filesystem
User Manual

Introduction | Installation | Usage | FAQ | Troubleshooting

1. Introduction

This manual aims to make installation and usage of your PhoneBook software as easy and pain-free as possible, by taking a 'walkthrough' approach.

1.1. What is 'PhoneBook'?

PhoneBook is a filesystem for Linux computers, which offers strong encryption with plausible deniability features.

It is designed for usage in jurisdictions where laws may mandate the disclosure of decryption keys on privately owned personal computers. With PhoneBook-encrypted volumes, a strategy of multiple encryption layers and 'chaffing' makes it difficult or impossible for an interrogator to determine whether you are fully complying with decryption orders.

PhoneBook is strongly inspired by the RubberHose project. However, in contrast to RubberHose, PhoneBook aims to be easy to install and use, targetted at intermediate Linux users and above.

For more information, refer to the (temporary) PhoneBook website at http://www.freenet.org.nz/phonebook.

1.2 Features

Uses a physical datastore from a regular filesystem - no need to allocate a dedicated physical partition
Datastore consists of a single directory, full of files with random 40-character filenames, constantly randomised timestamps, and all of a fixed size - there is nothing that will indicate to an attacker which physical file does what
Simple to build, install and deploy - just follow the easy walkthroughs later in this manual
Does not require kernel patching - instead, it automatically builds a separate kernel module
Free, GPL software
Powerful Blowfish encryption with SHA1 hashing
Every file in the physical datastore is encrypted with a different key and IV

1.3 Overview of Program Structure

The PhoneBook software uses the FUSE Linux Filesystem framework. Best to inform you in advance that FUSE builds and installs a linux kernel module (loaded separately, not patched into kernel source tree). So if the idea of a kernel module makes you nervous, you might like to check out FUSE and satisfy yourself that it's safe enough. We have done just that, and have a high level of confidence in FUSE.

2. Installation

Getting PhoneBook installed and running should be mostly drama-free, if you carefully follow these instructions.

2.1 Prerequisites

Before installing Phonebook, make sure you have all of the following:

Your system's root password
A 2.4-series kernel (2.6-series kernels should work as well, if you follow the instructions in the pbmodules/src/fuse directory, and apply the enclosed kernel patch, prior to trying to build PhoneBook)
A set of kernel header files which match your currently running kernel:
- If you have built your current kernel from source, these headers should already be present at the correct location
- If you are using a kernel built by your linux distribution vendor, you should be able to download/install the matching kernel headers as a separate package
Python 2.2 or later
Python development files (headers/libraries), matching your current version of Python
- If you are using your distro's python, you should be able to download/install a package named python-dev (or similar) from your distro vendor.
OpenSSL 'libcrypto' library, version 0.9.6 or later
OpenSSL libcrypto development files (headers and static library) matching your OpenSSL installation:
- You should see a directory /usr/include/openssl or /usr/local/bin/openssl with a bunch of headers
- You should see a file libcrypto.a in either /usr/lib or /usr/local/lib

2.2 Enclosed Software

As a Linux user, I have lost count of all the times I've tried to install a piece of software, only to find that it depends on n other packages, each of which depend on n' other packages, some of which are poorly packaged. As a result, I've ended up in Dependency And Compilation Hell. Strangely, the developers of such packages seem to have the unspoken attitude that if you're not a fluent programmer willing to put in the hours reading thousands of lines of unfamiliar source code, then you're too much of a n00b to deserve to use their software.

The PhoneBook developers don't share this attitude, and have tried hard to spare you of similar pain. Therefore, with the more obscure pieces of third party software, we have invoked the open source licenses and packaged copies of this software in with the PhoneBook distribution.

At present, there are only two such dependencies included in the package:

The FUSE (filesystem in userland) filesystem framework
The SSLCrypto Python cryptography bindings

All the other dependencies (mentioned above) are considered generic enough to not warrant inclusion in the PhoneBook distribution.

2.3 Building PhoneBook

Follow these simple steps:

Unpack your PhoneBook tarball into a safe, globally-accessible place (eg /usr/share or /var/lib)
cd into the top-level PhoneBook directory
type: make build

The top-level Makefile runs the python make.py script, which is responsible for:

Running autocrap and make on the enclosed FUSE software
Running Python distutils on the Python module within FUSE
Running Python distutils on SSLCrypto, the Python OpenSSL libcrypto wrapper

With all going well, all the requisite software should have built successfully, and you should be ready to install PhoneBook

Note - the most common cause of a failed build is if the FUSE package doesn't find your kernel headers. If this happens to you, edit the make.py file, find the kernelHeaders variable near the top, and edit it to point to the location of your kernel headers.

2.4 Installing PhoneBook

We have aimed for PhoneBook installation to be equally simple.

In fact, you can run the script as a normal user. The script will compose a set of commands to be executed as root, and will pass these commands to the standard su command (which will itself prompt you for the root password if you're not already root).

Simply, to install PhoneBook:

type: make install

2.5 What have I ended up wtih?

The make and installation of PhoneBook will have made the following changes to your system:

Written a symbolic link into /sbin/mount.pbfs, which points to the mount.py script in your PhoneBook directory
Written a symbolic link into /usr/bin/pbfs, which points to the util/pbfs.py in your PhoneBook directory
Written the following files into your Python site-packages directory:
- SSLCrypto.so - Python OpenSSL crypto wrapper
- fuse.py and _fusemodule.so - Python interface to your FUSE filesystem
Added fuse.o, the FUSE Kernel Module into your kernel modules tree (usually, /lib/modules/2.x.x/kernel/fs/fuse)

As you can see, nothing too dramatic.

3. Usage

Creating and using PhoneBook filesystems is pretty simple, and consists of the following steps:

Choose or create a directory to serve as the PhoneBook mountpoint
Choose or create an empty directory to serve as the PhoneBook datastore
Mount your PhoneBook filesystem
Run some quick commands to create and manage layers in your PhoneBook filesystem
Use your PhoneBook filesystem just like a normal Linux filesystem

3.1 Procure the Directories

You will need two separate (preferably empty) directories for your PhoneBook filesystem - one to serve as the mountpoint, and one to contain the datastore.

Typically, many people will create the mountpoint directory as /mnt/pbfs, and the datastore directory at /usr/share/pbfs (or even as directory .pbfs or pbfs in their home directory).

Just make sure that you (as user) have read/write/execute permission for both these directories. If in doubt, chmod both directories to 777 or ugo+rwx.

3.2 Mount the Filesystem

As with any Linux filesystem, there are two different ways of mounting a PhoneBook filesystem:

Directly, with a mount command
Implicitly, by creating an entry in /mnt/fstab

Note that you don't have to go to any special steps to create the filesystem - PhoneBook will create everything on the fly as needed.

3.2.1 Mounting Directly via Command Line (not advised)

Please note - in general, we advise you to fstab your mount, and do the mount as a user (see below). However, command-line mounting works fine as well.

Make sure you are root, and type the following command:

mount -t pbfs /path/to/datastore /path/to/mountpoint

If you are using the directory names above, this would be:

mount -t pbfs /usr/share/pbfs /mnt/pbfs

If the mount has succeeded, you should be able to type the command mount and see the following entry:

/proc/fs/fuse/dev on /mnt/pbfs type fuse (rw,nosuid,nodev)

If you see this, your filesystem is ready to use - just follow the instructions in the next section (managing layers), and you're ready to go.

3.2.2 Mounting via fstab (preferable)

Creating a mount entry in /etc/fstab (or wherever your distro puts its mount table) will make your life easier when mounting and unmounting. For one thing, you can allow yourself to mount the filesystem as a user. For another thing, you'll only need a single argument - the mountpoint.

To make your PhoneBook filesystem mountable via the fstab, just put into /etc/fstab the following two lines:

# PhoneBook filesystem mount
/usr/share/pbfs /mnt/pbfs pbfs defaults,noauto,user,exec 0 0

Note that you may need to change the /mnt/pbfs and /usr/share/pbfs to your PhoneBook mountpoint and datastore directories respectively.

3.3 Creating and Using Layers

Ok - if you've made it here, then congratulations. You have successfully built and installed PhoneBook, and completed your first mount of a PhoneBook filesystem.

However, your filesystem is not quite ready to use. You now need to set up one or more layers.

Don't worry - this is easy, and can be done with the PhoneBook pbfs utility (which should have been installed into /usr/bin).

To see the current state of the filesystem layers, type the command:

$ pbfs /mnt/pbfs listmap

You should see something like:

PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   ** USING TEMPORARY SCRATCH MAP **
  Layers:     ** NO LAYERS CURRENTLY IN MAP **

This tells us that the filesystem is active, but cannot be used, because there are no layers currently present.

Ok - let's now create and add a layer to our filesystem. We'll call this layer layer1, and give it the passphrase layer1pass.

Type the following command:

$ pbfs /mnt/pbfs addlayer layer1 layer1pass

You should see something like:

/usr/bin/pbfs: success: addlayer: new layer 'layer1' successfully appended

You can verify that this has worked by again typing:

$ pbfs /mnt/pbfs listmap

This time, you should see the output:

PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   ** USING TEMPORARY SCRATCH MAP **
  Layers:     layer1

This indicates that your filesystem now has a single layer, layer1. Note that you can add as many layers as you like.

3.4 Now We Can Use The Damn Thing!

Thanks for bearing with us so far. (Hopefully there haven't been any problems along the way).

We are now ready to do something with our filesystem.

Try typing in the following shell commands, and comparing the output to what we show below. As before, we are showing what you need to type in green, and the expected output in red. (Note that you don't type the '$' - it's the shell prompt).

Note that for now on, you might want to do this in a separate console (because the console from which you mounted the filesystem will be outputting a lot of annoying messages).

$ ls -l /mnt/pbfs
total 0
$ echo "Hello, world" > /mnt/pbfs/somefile
$ cat /mnt/pbfs/somefile
Hello, world
$ ls -l /mnt/pbfs/somefile
total 1
-rw-r--r--   0 root   root     13 2003-12-22 21:25 somefile
$ rm /mnt/pbfs/somefile
$ ls -l /mnt/pbfs/somefile
total 0
$

As you can see, we have created, read and deleted a single file.

Note also that the file exists with owner and group set to root. This is because all files get created with the user and group id of whoever mounted the filesystem. If you want these files to be created with uid/gid set to a user, then create an fstab entry (see above) and use this fstab entry to mount the filesystem.

Just for interest's sake, do an 'ls' command on your PhoneBook datastore directory (/usr/share/pbfs, if you used the conventions above). You should see a list of files with gibberish names and gibberish content.

Any attacker (eg a forensic engineer) analysing these files should not be able to determine which of the files are which. As you use your filesystem, and create more layers (and chaff), it will become impossible to determine just how many layermaps, layers or files there truly are (and which are just deliberate chaff).

3.5 Managing Layer-Maps

Recall above than when we issue the command pbfs /mnt/pbfs listmap we see an entry saying that we are using a temporary scratch map. Now is the time to explain what this means.

The greatest weakness in any encryption technology is the human factor - the vulnerability people have to slipping up and neglecting proper practice.

Any software that makes it more complicated to use good practice actually gives the user an incentive to be slack with security, which can be worse than no encryption (because a false sense of security is worse than a real knowledge of insecurity).

The whole business of 'layers' in PhoneBook can become an annoying pain in the butt after a short time. One can be tempted to use weak passwords, or not enough layers, which will make your filesystem open to all manner of dictionary attacks and plain old human-intuitive hacking.

To remedy this, we have added a mechanism we call layer maps. Basically, a layer map is a determined set of layers in a determined order.

You can create a named layer map (with its own passphrase), and create/add any combination of layers to it. Once you've done this, you can just open the map with a single name and passphrase - it will reactivate all the layers in the right order automatically.

Let's put this into practice. Below, we will:

mount our filesystem
create a named layermap
add three layers to it
unmount the filesystem
mount the filesystem again
re-open the layermap we created
verify that the correct layers are present

IMPORTANT NOTE - keep pen and paper handy for noting all passphrases for your layers and layermaps. Under no circumstances should you store these on any hard disk (except maybe a floppy, itself secured by PhoneBook or another encryption tool).

Ok - let's do it (make sure that your filesystem is not presently mounted):

$ su
Password: (type in your root password)

(mount the filesystem)

# mount -t pbfs /usr/share/pbfs /mnt/pbfs

(verify that we are currently using the 'scratch map')

# pbfs /mnt/pbfs listmap
PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   ** USING TEMPORARY SCRATCH MAP **
  Layers:     ** NO LAYERS CURRENTLY IN MAP **

(create a new map)

# pbfs /mnt/pbfs openmap mymap mypass
/usr/bin/pbfs: success: now using layermap 'mymap'

(notice that the map is active, but has no layers)

# pbfs /mnt/pbfs listmap
PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   mymap
  Layers:     ** NO LAYERS CURRENTLY IN MAP **

(add a couple of layers)

# pbfs /mnt/pbfs addlayer layer1 layer1pass
/usr/bin/pbfs: success: addlayer: new layer 'layer1' successfully appended
# pbfs /mnt/pbfs addlayer layer2 layer2pass
/usr/bin/pbfs: success: addlayer: new layer 'layer2' successfully appended

(notice that these layers are now on the map)

# pbfs /mnt/pbfs listmap
PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   mymap
  Layers:     layer1:layer2

(unmount and re-mount the filesystem)

# umount /mnt/pbfs
# mount -t pbfs /usr/share/pbfs /mnt/pbfs

(notice that no layers or map are presently active)

# pbfs /mnt/pbfs listmap
PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   ** USING TEMPORARY SCRATCH MAP **
  Layers:     ** NO LAYERS CURRENTLY IN MAP **

(open up the map we created a moment ago)

# pbfs /mnt/pbfs openmap mymap mypass
/usr/bin/pbfs: success: now using layermap 'mymap'

(notice that our layer stack is recalled as it was)

# pbfs /mnt/pbfs listmap
PhoneBookFS Layer Map Report:
  Mountpoint: /mnt/pbfs
  Map Name:   mymap
  Layers:     layer1:layer2

So, what the hell does all this mean?

It means that with 'layermaps', you can create specifications for 'sets of layers in particular order', that can be stored and recalled with a single name and passphrase.

Needless to say, a layermap passphrase is exceedingly sensitive, because it yields up all the names and passphrases for the layers it contains. So guard a layermap password like you guard your root password - in fact, guard it even better!

3.6 The Magic '__layers' Directory

Normally, when you read a file on your filesystem, the version of the file you get comes from the top-most layer that has this file.

For instance, with the above examples, if layer1 and layer2 both have a file /somedir/somefile.jpg (the path is relative to the mountpoint), and you try to open /mnt/pbfs/somedir/somefile.jpg, you will get the version of somefile.jpg from layer1.

On the other hand, any files you write to the filesystem will get written into the top-most layer in the stack - in this case, layer1.

However, to take full and convenient advantage of the layered crypto features of PhoneBook, you will at times need to control exactly which layers you read from and write to.

To this end, mounted PhoneBook filesystems have a 'magic directory' called __layers. Each currently active layer appears by name as a subdirectory of __layers.

For example, make sure your have your filesystem mounted, and the map mymap open (as per above). Then try the following:

# ls -l /mnt/pbfs/__layers
total 2
dr-xr-xr-x    1 root     root         1024 2003-12-22 22:31 layer1
dr-xr-xr-x    1 root     root         1024 2003-12-22 22:31 layer2

If you want to operate explicitly on layer1, just stick __layers/layer1/ into the path. Ditto for layer2.

Using the __layers pseudo-directory, you can:

copy/move files between layers
create different versions of the same file in different layers
anything else which meets your security needs and desires.

Note that you can have many different layermaps, which share any combination of the same layers. For instance, you could have map mymap1, which contains layers layer1, layer2, layer3. You could have map mymap2, which contains layers layer2, layer4.

Recall that you could even have two or more layermaps with the same map name, but different passphrases. If you do this, then Phonebook will treat them as completely distinct layermaps.

You can even do this with layers - have two or more layers with the same name, but with different passphrases. This will result in distinct layers. (If you do this, though, take care when building your layermaps, so that you have the right version of each named layer).

3.7 More About The pbfs Utility

The pbfs utility gives you the means to talk to a live-running PhoneBook filesystem, and perform tasks such as:

creating layermaps
viewing the structure of layermaps
adding/removing layers to/from layermaps
creating layers
switching from one layermap to another
adding 'chaff' to the datastore, for plausible deniability

Here are the pbfs commands and options:

pbfs -h|--help|help [command]

Prints a help summary with a list of available commands. If command is given (and is a known command), it prints more detailed info on that command.

pbfs /path/to/mountpoint listmap

Prints the name of the current layermap, and the layers it uses.

pbfs /path/to/mountpoint openmap mapname [mappass]

Closes the current layermap, and loads a new one.

If no layermap (specified by name mapname and passphrase mappass) currently exists, it will be created, in which case it will be initially empty, and will need one or more layers to be added before it can be used.

If you don't give the map passphrase, you will be given a non-echoing prompt for it.

Be warned - if you specify the passphrase on the command line, it can end up in shell history files (defeating the whole purpose of PhoneBook). Another warning - DO NOT put passphrases into any script files!

pbfs /path/to/mountpoint destroymap mapname [mappass]

Destroys the current layermap, and its file(s) on the datastore.

Note that this does not delete the layers referenced therein, or any of their files.

If you don't give the map passphrase, you will be given a non-echoing prompt for it.

pbfs /path/to/mountpoint addlayer layername [layerpass]

Opens a layer, and appends it to the bottom of the current layermap's layer stack.

If no layer (specified by name layername and passphrase layerpass) currently exists, it will be created.

If a named layermap is active (not the initial 'scratch layermap'), it will be automatically saved so that it remembers the newly added layer.

If you don't give the map passphrase, you will be given a non-echoing prompt for it.

pbfs /path/to/mountpoint pushlayer layername [layerpass]

Same as addlayer, but pushes the newly opened (or created) layer to the top of the current layermap's layer stack.

If you don't give the map passphrase, you will be given a non-echoing prompt for it.

pbfs /path/to/mountpoint droplayer layername

Removes the named layer layername from the layermap stack.

Note that the layer itself, and its contents, will be completely unaffected.

If a named layermap is active (not the initial 'scratch layermap'), it will be automatically saved so that it remembers the newly added layer.

pbfs /path/to/mountpoint poplayer

Drops the topmost layer from the layermap stack.

Note that the layer itself, and its contents, will be completely unaffected.

If a named layermap is active (not the initial 'scratch layermap'), it will be automatically saved so that it remembers the newly added layer.

pbfs /path/to/mountpoint makechaff size

Adds a quantity of 'chaff' to the physical datastore, to provide plausible deniability about the actual amount of real data in the store.

Since all the files in the datastore have hashed or random names, encrypted or random contents, and random dates, it should prove very difficult for an attacker to discern whether each given file is part of a layermap, part of an inode, part of a file or just a piece of chaff.

If you find yourself in any situation of pressure to disclose decryption keys, you can assert to your attacker that you have executed this command several times and forgotten what size argument you specified.

The very presence and implementation of this command gives you a measure of plausible deniability. However, you are advised to actually use it, and add an amount of chaff which is between 10% and 400% of the total amount of real data, or perhaps 100% to 500% of the size of the largest layer (you can determine the size of each open layer with the command:

du -s /path/to/mountpoint/__layers/layername

The size argument is the number of bytes of chaff to generate. It may have a suffix of k, m or g, meaning kilobytes, megabytes or gigabytes respectively. (Note that the suffix is case-insensitive).

Since each physical datastore file is a fixed size (default 16kB), the size you specify will be rounded up to the nearest 16k.

You can get this information by typing 'pbfs -h'.

3.9 Security Precautions

Here are some guidelines to minimise the possibility of your data being compromised:

Use Good Passphrases
- We perceive that the greatest vulnerability of PhoneBook is to dictionary attacks, where the attacker uses a program that randomly constructs brute-force passphrases from common words, numbers and expressions. To defeat such attacks, make sure your passphrases are at least sixteen characters, and contain character combinations that don't occur in dictionaries or normal human expression
Create Lots of Fake Layers and Files
- The more decoy files you have in the datastore, the harder it will be for an attacker to determine just how much real content actually exists. Alternatively, you could lie under interrogation and simply tell your attacker that you have created a lot of fake data, but this could be risky. Future versions of Phonebook are likely to feature automatic periodical chaff generation.
Don't Enter Passphrases On The Command Line
- Although the pbfs utility allows this, it's not a good idea since your passphrases can end up in your shell command history files
Don't Hard-Code Passphrases Into Command Scripts, or into ANY File
- That would be like buying a high-quality safe, and sticking the combination on a post-it note on the door. If you don't trust yourself to remember your passphrases, write them down on a piece of paper and keep that piece of paper secure.
Use An Encrypted Swap Partition
- If your linux distribution supports this, it will save you much heartache. You won't have to worry about the Phonebook internal data structures getting swapped out to disk, revealing layer details and passphrases.
- If your linux distro doesn't support swapfile encryption, there is an excellent package called loop-AES, downloadable from http://loop-aes.sourceforge.net, which can be easily set up for swapfile encryption via a loop device. Be sure to follow its instructions to the letter. The README instructions are fairly detailed, but will lead you clearly step-by-step through the whole process. After building/installing the AES-powered loop driver, just follow the instructions in the swapfile encryption example. Don't be timid - I'm no kernel hacker, and it only took me 20 mins or less from start to finish.
Don't Export pbfs-Mounted Directories
- Unless you feel confident in your network's security. Forensic attackers in many jurisdictions are now legally entitled to crack into your system with any means they see fit - eg exploiting known vulnerabilities in servers you may be running. This is bad enough, but exporting your pbfs mounts will only exacerbate the danger.
Set 'noatime' On The Partition Hosting The Datastore
- PhoneBook fights against analysis of the physical datastore in different ways. For one, all physical files are the same size. Secondly, each file is encrypted with a different Blowfish key. Thirdly, the files are given random names (or, in some cases, hashes). Fourthly, the atimes/mtimes of all physical files get randomised upon mount, and every time a physical file gets written or changed, its atime and mtime get randomised again. But, if you want to be doubly sure, you could set noatime on the partition which hosts the datastore directory.
Generate chaff often
- This is the whole key to your plausible deniability. If you (say) have a physical datastore with 240MB of files, and you only provide access details for 180MB worth of data, your attacker will want you to account for the remaining 60MB. You may in truth have 40MB of high-sensitivity material and 20MB of chaff, but you can freely tell your attacker that there is in fact 60MB of chaff. Your attacker will have a difficult time trying to prove otherwise.
- If you don't generate chaff, and you don't have a familiar 'feel' of the makechaff command, your position of deniability could be seriously weakened.

3.9 Conclusion

If you have followed the walkthrough in this chapter, and improvised with your own experiments, you will have:

mounted/unmounted your own PhoneBook filesystem(s)
created two or more named layers
created one or more layermaps, and specified an ordered stack of layers within these layermaps
used the __layers pseudo-directory to do file reads/writes targetted at explicit layers.

Hopefully, you should now be seeing how you can construct several different layermaps, each intended for access by different classes of viewers (eg friends, business associates, business rivals, hostile forensic analysts etc).

Also, you will most likely realise how you can create 'chaff' layers - to permanently and irreversibly pollute your datastore with random gibberish - to destroy any hope an attacker may have for discovering just how many layermaps and layers there actually are.

We expect by this time that the seeds of a filesystem security strategy will already be sprouting in your mind.

4. Frequently-Asked Questions

What happens if I forget the name or passphrase for a layermap?

You're out of luck. All you can do is try to remember which layers were in that layermap, and in which order, and create a whole new layermap with the same set of layers in the same order. You do know these layers' names and passphrases, don't you!?

What happens if I forget the name or passphrase for a layer?

If the layer is referenced within a layermap, and you can remember the name/passphrase of that layermap, you're safe. Just mount your filesystem, open the layermap, and move the files out of there and into a new layer (and be more careful with the name/passphrase next time).

If the layer is not referenced within the layermap, then your files are history. They're still in the datastore, but stored under gibberish filenames and with heavy encryption. Doesn't help you though, so you'd best just kiss them goodbye and learn from the experience.

What happens if I type in the wrong name and/or passphrase for a layer?

If the layer doesn't already exist (with this different name and passphrase), a new empty one will be created. You will not receive any 'incorrect name/password'-type messages.

What happens if I type in the wrong name and/or passphrase for a layer map?

Same situation as with previous question.

How do I back up my PhoneBook filesystem?

Easy. Just unmount the filesystem, and back up the datastore directory

Can I safely export a PhoneBook filesystem within my local network?

Maybe. If you trust your network's security, then you should be able to export the filesystem's mount point (eg with nfs) as you do with other filesystems. But if you do so, then please note that layer/layermap namess and passphrases will be flying around the network in plaintext form - if someone's sniffing your network, you're toast.

Another alternative is to export the datastore directory from your fileserver box, and install PhoneBook and mount the filesystem on your client box. That way, sensitive traffic won't flow over the network - just creates/reads/writes to physical datastore files (which is no help to an attacker).

Can I mount the same PhoneBook datastore more than once at any one time?

You could, but I won't make any promises about what this will do to the integrity of your filesystem. At least, files you've written can go MIA, at worst, files and even whole directories can get irreversibly corrupted.

It's definitely something we wouldn't recommend if you feel your data is worth anything

Will future versions of PhoneBook support multiple-mounting of the same datastore?

If you're talking about mounting the datastore and exporting the mountpoint, then that should already be working now.

But if you're talking about having several instances of PhoneBook mounting the same physical datastore at the same time, then that's one beastly complex can of worms - our answer here is "sure, it'll be supported in future versions, just as soon as you send in the patches and we've had a chance to review and test them".

What crypto are you using?

256-bit Blowfish, CFB mode, plus SHA1 hashes. Period. No asymmetrical crypto needed.

How are you generating your random numbers?

The SSLCrypto python module just hooks into OpenSSL libcrypto's random number generation routines. In successive versions of PhoneBook, I'll look at providing easy and more automatic ways to seed this prng.

How are the files in the datastore stored, named and encrypted?

For each 'logical' file (or directory) as seen from the mountpoint, two physical files get written to the datastore - an inode file (with the stat properties and a few other fields), plus the actual data file.

The name of the inode file is deterministically hashed from a combination of the layer name and passphrase plus a randomly generated 31-bit inode number. The passphrase and IV for the inode file are a deterministic hash of layername+layerpassphrase+inodenum. The root directory inode for each layer differs only in that the inode number is hardwired as zero.

The name of the physical data file is randomly generated, as is its passphrase and IV. These details are stored in cleartext within the inode file, protected by the encryption of the inode file.

The other file type in the physical datastore is the layermap file. Name of this file, as well as passphrase and IV, are a deterministic hash of permutations of layermapname+layermappassphrase. Great reliance is placed on the difficulty of extracting predictable patterns in SHA1 hashes.

As can be seen here, the layermap names and passphrases effectively serve as 'skeleton keys', which can unlock the names, passphrases and IVs of all the constituent layers and files, which is why, in above discussion, the need to protect the layermap passphrases, never storing them in the clear on the filesystem, is strongly emphasised.

Will you be releasing any graphical programs for managing the layers, or will there only ever be the pbfs console program?

We'll get around to writing a graphical layer and layermap management program - it's on the list. If you want to write one in the meantime, we suggest doing it in Python and using the sendPbCommand function in pbfs.py (command dict in, response dict out). This will save you much pain.

How does pbfs 'talk' to the running filesystem code?

When the filesystem starts up, it spawns a thread which creates a unix-domain socket in /tmp (eg /tmp/pbfs.mnt_pbfs). The pbfs utility does a similar munge on the mountpoint path to find this socket file; it connects to this socket, sends the command to the filesystem, and gets back the response.

This replaces an ugly earlier scheme where Phonebook used pseudofiles in the mountspace for writing commands and reading back responses.

Will you be releasing a version of this program for Windows?

Sure - send in your code and I'll check it out. Make sure any non-python code compiles cleanly with MSVC6 (sadly, the standard compiler for winshit operating systems). If it works and passes tests/audits, we'll add it to the next release.

What's the story with hard links? How come they sometimes work, and sometimes not?

One constraint of the Phonebook security model is that hard file links can only exist within the bounds of an individual layer. You cannot hardlink from one layer to another.

The only reliable way to create file hardlinks is to do so within the /__layers/layername/... path.

I'm getting a lot of 'permission denied' errors. What gives?

Some possible causes include:

Insufficient permissions on the datastore or the mountpoint directory - if in doubt, chmod both of these to 777 or ugo+rwx.
You have mounted/unmounted/remounted the filesystem as different users. If in doubt, do:
su -c "chmod ugo+rw /path/to/datastore/*"
Alien psychic transmissions from a past life are interfering with your computer's interdimensional vibe
We've screwed up badly somewhere - please try to distil into a simple reproducible test case and send in a bug report

Can I Have Several Different PhoneBook Filesystems Running At The Same Time On The Same Box?

We can't think of any reason why not. Do please make sure, though, to perform each mount with its own unique datastore and mountpoint directories. Having two or more mounts with the same datastore directory, or the same mountpoint, is asking for Very Bad Things to happen. (Maybe I should stick in some code to sniff out /proc/mounts and head off such an occurrence).

Can I Distribute PhoneBook Filesystems via Email or on Disk/CD?

Most definitely yes.

To send a filesystem via email, just tar or zip up the datastore directory and send it as an email attachment. You can choose to securely distribute different layermap name/passphrase details to different people, according to the level of trust.

To distribute a filesystem via CD or floppy, just copy/burn the datastore's physical files onto that media. You should be able to (say) mount a CD containing PhoneBook datastore files into your OS, then mount that mount into PhoneBook.

For example:

# mount /dev/scd0 /mnt/cdrom
# mount -t pbfs /mnt/cdrom /mnt/pbfs
# pbfs openmap /mnt/pbfs mapname
Passphrase:
#