"Fossies" - the Fresh Open Source Software Archive

Member "cryptofs-0.6.0/doc/README.xml" (3 Feb 2007, 9785 Bytes) of package /linux/misc/old/cryptofs-0.6.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="iso-8859-15"?>
    2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN">
    3 <article>
    4     <articleinfo>
    5     <title>CryptoFS</title>
    6     <author>
    7         <firstname>Christoph</firstname>
    8         <surname>Hohmann</surname>
    9         <honorific>B.Sc</honorific>
   10         <affiliation>
   11         <address><email>reboot@gmx.ch</email></address>
   12             </affiliation>
   13     </author>
   14     <copyright>
   15             <year>2003-2006</year>
   16             <holder>Christoph Hohmann</holder>
   17     </copyright>
   18     </articleinfo>
   19     <sect1>
   20         <title>What's CryptoFS</title>
   21     <para>
   22         CryptoFS is a encrypted filesystem for Filesystem in Userspace
   23         (FUSE) and the Linux Userland FileSystem (LUFS).  Visit <ulink
   24         url="http://fuse.sourceforge.net/">http://fuse.sourceforge.net/</ulink>
   25         for more information on FUSE or <ulink
   26         url="http://lufs.sourceforge.net/lufs/">http://lufs.sourceforge.net/lufs/</ulink>
   27         for more information on LUFS.
   28     </para>
   29         <para>
   30         CryptoFS will use a normal directory to store files encrypted.
   31         The mountpoint will contain the decrypted files. Every file
   32         stored in this mountpoint will be written encrypted (data
   33         and filename) to the directory that was mounted. If you
   34         unmount the directory the encrypted data can only be access
   35         by mounting the directory with the correct key again. Like
   36         other FUSE/LUFS filesystems it does not need root access
   37         or any complicated setup like creating a filesystem on a
   38         encrypted disk using the loop device.
   39         </para>
   40     <para>
   41         CryptoFS can be build for FUSE and LUFS. When you build for
   42         FUSE you get a program to mount the filesystem. For LUFS a
   43         shared library will be built that can be used by LUFS's lufsd.
   44         Both methods can use the same encrypted directory.
   45     </para>
   46     </sect1>
   47 
   48     <sect1>
   49     <title>Why CryptoFS?</title>
   50     <para>
   51         I first used the evfs kernel patch that does nearly the same thing
   52         as CryptoFS. But it seems that it has been abandoned. The last patch
   53         was available for kernel 2.4.20 and has not been updated for newer
   54         kernels since then. When I found LUFS I thought I could be a good
   55         base for a crypto filesystem that works like evfs and allows a user
   56         to mount any directory as an encrypted storage without having root
   57         access and creating a crypto filesystem using the loop device. So
   58         when I found no other program that offers this posibilities I started
   59         to write my own filesystem for LUFS. Unfortunately LUFS seems to be
   60         dead too, so CryptoFS can now be build for FUSE too which has already
   61         made it into the official Linux kernel package.
   62     </para>
   63     </sect1>
   64 
   65     <sect1>
   66     <title>Requirements</title>
   67     <para>
   68         You either need FUSE or LUFS to use CryptoFS.
   69         For FUSE you need the FUSE tools, library and
   70         kernel module.  You also need the FUSE development
   71         files to build the FUSE filesystem. See <ulink
   72         url="http://fuse.sourceforge.net/">http://fuse.sourceforge.net/</ulink>
   73         for more information and downloads. If you don't want to build
   74         CryptoFS for FUSE you can use the --disable-fuse configure
   75         switch. Otherwise it will be build when the development files
   76         are found on the system. For LUFS you only have to install
   77         the LUFS tools and load the LUFS kernel module. See <ulink
   78         url="http://lufs.sourceforge.net/lufs/">http://lufs.sourceforge.net/lufs/</ulink>
   79         on how to do this and downloads for LUFS. If you want
   80         to disable building CryptoFS for LUFS you can use the
   81         --disable-lufs configure switch.  As the LUFS module has no
   82         requirements it will be build by default.    Installing and
   83         setting up LUFS and FUSE will not be covered by this document.
   84     </para>
   85     <para>
   86         CryptoFS uses Libgcrypt from <ulink
   87         url="ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/">ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/</ulink>
   88         (version >= 1.1.44) and GLib from <ulink
   89         url="http://www.gtk.org">http://www.gtk.org</ulink>
   90         (version >= 2.6). You must have installed these packages
   91         correctly before running CryptoFS's "configure" script.
   92     </para>
   93     <para>
   94         Optionally CryptoFS can use the <ulink
   95         url="ftp://ftp.gnupg.org/gcrypt/pinentry/">PIN Entry</ulink>
   96         utility by <ulink url="http://www.gnupg.org/">GnuPG</ulink>
   97         to ask the user for the filesystem's password. If the pinentry
   98         program is found on the system CryptoFS will be automatically
   99         built with PIN Entry support. Otherwise it will fall back
  100         to the old console input method.
  101     </para>
  102     </sect1>
  103 
  104     <sect1>
  105     <title>Usage</title>
  106         <para>
  107         First you have to set up the source directory by copying
  108         the file cryptofs.conf to &lt;source&gt;/.cryptofs. Where
  109         &lt;source&gt; is the directory where you want to store
  110         the encryted files. You can adjust the values in the file,
  111         but the default should work fine.
  112     </para>
  113     <para>
  114         For FUSE you have to run cryptofs that should be in an executeable
  115         path after "make install". The required options are
  116         <programlisting><![CDATA[     cryptofs --root=<source> <dest> ]]></programlisting>
  117         &lt;dest&gt; is the directory where the filesystem containing
  118         the decrypted files will be mounted.
  119     </para>
  120     <para>          
  121             For LUFS put the shared library into a directory where the system linker can find
  122         it (this will usually be done by "make install") or add the directory
  123         to the search path by setting the LD_LIBRARY_PATH environment varibale.
  124     </para>
  125     <para>
  126         After that you can mount the source directory with
  127         <programlisting><![CDATA[     lufsmount cryptofs://<source> <dest> ]]></programlisting>
  128     </para>
  129     <para>
  130         You will be asked for the password you want to use for this filesystem. It
  131         will be used to generate the cipher key.
  132     </para>
  133     <para>
  134         After that you should be able to use the &lt;dest&gt; directory like any other
  135         directory, but all data will be read and written to the &lt;source&gt; directory
  136         in an encrypted form.
  137     </para>
  138     </sect1>
  139 
  140     <sect1>
  141     <title>How does it work?</title>
  142     <sect2>
  143         <title>The .cryptofs config file</title>
  144         <para>
  145         The CryptoFS config file in each encryted directory contains 4 options.
  146         These are
  147         <variablelist>
  148             <varlistentry>
  149             <term>cipher</term>
  150             <listitem>
  151                 <para>
  152                 The cipher algorithm used to encrypt files and filenames.
  153                 This has to be a cipher name known by libgcrypt.
  154                 </para>
  155             </listitem>
  156             </varlistentry>
  157             <varlistentry>
  158             <term>md</term>
  159             <listitem>
  160                 <para>
  161                 The message digest algorithm used to generate the cipher
  162                 key. This has to be a message digest name known by
  163                 libgcrypt.
  164                 </para>
  165             </listitem>
  166             </varlistentry>
  167             <varlistentry>
  168             <term>blocksize</term>
  169             <listitem>
  170                 <para>
  171                 An encrypted file can not be randomly accessed like a normal
  172                 file and CryptoFS always reads and writes blocks of this size.
  173                 </para>
  174             </listitem>
  175             </varlistentry>
  176             <varlistentry>
  177             <term>salts</term>
  178             <listitem>
  179                 <para>
  180                 This is the number of subkeys CryptoFS will generate to
  181                 encrypt blocks.
  182                 </para>
  183             </listitem>
  184             </varlistentry>
  185         </variablelist>
  186         <emphasis>NOTE:</emphasis> Before 0.4.0 CryptoFS used a different config file format.
  187         The LUFS module can still read this format. The FUSE program only supports
  188         the new format. If you want to switch from LUFS to FUSE you have to
  189             replace .cryptofs with a file in the new format.
  190         </para>
  191     </sect2>
  192     <sect2>
  193         <title>Encryption</title>
  194         <para>
  195         When a filesystem is mounted CryptoFS first generates a key for the
  196         requested cipher algorithm (cipher option) using the message
  197         digest function (md option). Every algorithm has a specific key size
  198         and every message digest function has a specific length of the
  199         generated message digest. If the message digest size is smaller then
  200         the keysize the message digest will be repeated until the key size
  201         is reached.
  202         </para>
  203         <para>
  204         After they primary key has been generated n (= salts option= subkeys
  205         (initialization vectors) will be generated by encrypting 0 bytes with
  206         a 0 initialization vector. These will later be used to encrypt blocks
  207         with different subkeys to make sure the cipher text will first repeat
  208         after (salts * blocksize) bytes (If the same data is encrypted).
  209         </para>
  210         <para>
  211         When files or links are created or renamed the name will be encoded
  212         with the selected cipher, the primary key and the first subkey.
  213         The result will then be encoded using a modified Base64 algorithm
  214         because the encrypted filename could contain characters that are not
  215         allowed by the target filesystem. (The original Base64 algorithm
  216         uses '/' for encoding. This is the directory delimiter so it was
  217         replaced by '_')
  218         </para>
  219         <para>
  220         When files are written the data will be encrypted. CryptoFS always
  221         has to write full blocks. So if only a part of a block should be
  222         written the original block will first be read, decrypted, the part
  223         replaced and then the result then written encrypted back to disk.
  224         To keep this performant that block size must not be too large.
  225         But to make sure the cipher text does not repeat to early, CryptoFS
  226         uses salts to encrypt blocks. Every block will be encoded with
  227         the (blocknumber module salts)th salt. (NOTE: Linux always reads
  228         or writes "pages" of size 4096 bytes, these writes will be
  229         forwarded by lufsd to CryptoFS. So if you use a blocksize of
  230         4096 bytes reading the old block before writing can be omitted
  231         and writing should be faster)
  232         </para>
  233     </sect2>
  234     </sect1>
  235 
  236     <sect1>
  237     <title>Download</title>
  238     <para>{download}</para>
  239     </sect1>
  240 </article>