"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 <source>/.cryptofs. Where
109 <source> 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 <dest> 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 <dest> directory like any other
135 directory, but all data will be read and written to the <source> 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>