documentation for 1.0 release

This commit is contained in:
Jaromil 2011-03-10 12:53:21 +01:00
parent f35bbb1515
commit 16e723fa9e
6 changed files with 284 additions and 188 deletions

View File

@ -7,5 +7,3 @@ Testing and fixes are contributed by Dreamer and Hellekin O. Wolf
Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth

View File

@ -1,3 +1,10 @@
March 2011 - 1.0
Clean and stable. Now passwords are handled exclusively using
pinentry. Also support for steganography of keys (bury and exhume)
was added to the commandline. Commandline and desktop operations
are separate so that tomb can be used via remote terminal.
February 2011 - 0.9.1 February 2011 - 0.9.1
Sourcecode cleanup, debugging and testing. Sourcecode cleanup, debugging and testing.

2
README
View File

@ -12,7 +12,7 @@ X~ `?888888hx~ ...ue888b .888: x888 x888. 8888 .
' "*88888888* 'Y" `~ " `"` `%888*%" ' "*88888888* 'Y" `~ " `"` `%888*%"
^"***"` "` ^"***"` "`
a simple commandline tool to manage encrypted storage v.0.9.2 a simple commandline tool to manage encrypted storage v.1.0
http://tomb.dyne.org http://tomb.dyne.org

View File

@ -27,6 +27,11 @@ USB stick.
** Documentation ** Documentation
"*All I know is what the words know, and dead things, and that makes
a handsome little sum, with a beginning and a middle and an end, as
in the well-built phrase and the long sonata of the dead.*"
Samuel Beckett
First of all the usual info you'd expect a software to provide: First of all the usual info you'd expect a software to provide:
- [[README]] - [[README]]
@ -47,7 +52,6 @@ To open a tomb is sufficient to click on it, or use the command **tomb-open**
When a tomb is open your panel will have a little icon in the tray When a tomb is open your panel will have a little icon in the tray
reminding you that a tomb is open, offering to explore it or close it. reminding you that a tomb is open, offering to explore it or close it.
[[images/awesome-shot.png]]
To make safety copies of your keys, tomb lets you "bury a key" inside To make safety copies of your keys, tomb lets you "bury a key" inside
an image (using steganography techniques) and of course "exhume" an image (using steganography techniques) and of course "exhume"
@ -55,6 +59,8 @@ buried keys from pictures where they are hidden. Actually it is very
hard to guess when something is hidden inside a picture without hard to guess when something is hidden inside a picture without
knowing the password used in steganography. knowing the password used in steganography.
[[images/awesome-shot.png]]
See the [[manual.html][manpage]] for more information on how to operate Tomb from the See the [[manual.html][manpage]] for more information on how to operate Tomb from the
text terminal. text terminal.
<example> <example>
@ -87,7 +93,7 @@ Please report bugs on <http://bugs.dyne.org>.
*** Who needs Tomb *** Who needs Tomb
Democracy requires Privacy as much as Freedom of Expression. "*Democracy requires Privacy as much as Freedom of Expression.*" Anonymous
Our target community are desktop users with no time to click around, Our target community are desktop users with no time to click around,
sometimes using old or borrowed computers, operating in places sometimes using old or borrowed computers, operating in places

268
doc/web/views/manual.html Normal file
View File

@ -0,0 +1,268 @@
Content-type: text/html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of tomb</TITLE>
</HEAD><BODY>
<H1>tomb</H1>
Section: User Commands (1)<BR>Updated: February 12, 2011<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<P>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
Tomb - the Crypto Undertaker
<P>
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<B><DL COMPACT>
<DT>tomb [options] command [arguments]<DD>
</B>
<B><DT>tomb-open [file]<DD>
</B>
<B><DT>tomb-status mountpoint<DD>
</B>
<P>
</DL>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
<P>
Tomb is an application to manage the creation and access of encrypted
storage files: it can be operated from commandline and it can
integrate with a user's graphical desktop.
<P>
Tomb generates encrypted storage files to be opened and closed using
their associated keys, which are also protected with a password chosen
by the user. To create, open and close tombs a user will need super
user rights to execute the tomb commandline utility.
<P>
A tomb is like a locked folder that can be safely transported and
hidden in a filesystem; it encourages users to keep their keys
separate from tombs, for instance keeping a tomb file on your computer
harddisk and its key file on a USB stick.
<P>
For simplified use, the command <I>tomb-open</I> starts a wizard that
guides users in the creation of a new tomb or, if a tomb file is
specified as <I>argument</I>, it opens it and makes it accessible in a
default location under the /media folder, starting the status tray
applet (<I>tomb-status</I>) if a desktop is present.
<P>
<P>
<A NAME="lbAE">&nbsp;</A>
<H2>COMMANDS</H2>
<P>
<B><DL COMPACT>
<DT>create<DD>
</B>
Creates a new encrypted storage tomb and its key, named as specified
by the given <I>argument</I>.
<P>
<B><DT>open<DD>
</B>
Opens an existing tomb file specified in the <I>first argument</I>. If
a <I>second argument</I> is given it will indicate the <I>mountpoint</I>
where the tomb should be made accessible, if not then the tomb is
mounted in a directory named after the filename and inside /media.
<P>
<B><DT>close<DD>
</B>
Closes a currently open tomb. When <I>an argument</I> is specified, it
should point to the tomb mount on /dev/mapper; if not specified and
only one tomb is open then it will be closed; if multiple tombs are
open, the command will list them on the terminal. The special
<I>argument</I> 'all' will close all currently open tombs.
<P>
<B><DT>bury<DD>
</B>
Hides a tomb key (<I>first argument</I>) inside a jpeg image (<I>second
argument</I>) using steganography: the image will change in a way that
cannot be noticed by human eyes and the presence of the key inside it
isn't detectable without the right password. This option is useful to
backup tomb keys in unsuspected places; it uses steghide and the
serpent encryption algorithm.
<P>
<B><DT>exhume<DD>
</B>
Extracts a named tomb key (<I>first argument</I>) from a (jpeg) image file
(<I>second argument</I>) known to be containing it, if the right password is
given. This is used to recoved buried keys from unsuspected places.
<P>
</DL>
<A NAME="lbAF">&nbsp;</A>
<H2>OPTIONS</H2>
<B><DL COMPACT>
<DT>-s </B><I>&lt;MBytes&gt;</I><DD>
When creating a tomb, this option must be used to specify the size of
the new <I>file</I> to be created, in megabytes.
<B><DT>-k </B><I>&lt;keyfile&gt;</I><DD>
When opening a tomb, this option can be used to specify the location
of the key to use. Keys are created with the same name of the tomb
file adding a '.gpg' suffix, but can be later renamed and transported
on other media. When a key is not found, the program asks to insert a
USB storage device and it will look for the key file inside it.
<B><DT>-n<DD>
</B>
Skip processing of post-hooks and bind-hooks if found inside the tomb.
See the <I>HOOKS</I> section in this manual for more information.
<B><DT>-h<DD>
</B>
Display a help text and quit
<B><DT>-v<DD>
</B>
Display version and quit
<B><DT>-q<DD>
</B>
Run more quietly
<DT>-D<DD>
Print more information while running, for debugging purposes
<P>
</DL>
<A NAME="lbAG">&nbsp;</A>
<H2>HOOKS</H2>
<P>
Hooks are special files that can be placed inside the tomb and trigger
actions when it is opened and closed; there are two kinds of such
files: <I>bind-hooks</I> and <I>post-hooks</I> can be placed in the
base root of the tomb.
<P>
<B><DL COMPACT>
<DT>bind-hooks<DD>
</B>
This hook file consists of a simple two column list of files or
directories inside the tomb to be made directly accessible inside the
current user's home directory. Tomb will use the &quot;mount -o bind&quot;
command to bind locations inside the tomb to locations found in $HOME
so in the first column are indicated paths relative to the tomb and in
the second column are indicated paths relative to $HOME contents, for
example:
<P>
<BR>&nbsp;&nbsp;mail&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mail
<BR>&nbsp;&nbsp;.gnupg&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.gnupg
<BR>&nbsp;&nbsp;.fmrc&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.fetchmailrc
<BR>&nbsp;&nbsp;.mozilla&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.mozilla
<P>
<B><DT>post-hooks<DD>
</B>
This hook file gets executed as user by tomb right after opening it;
it can consist of a shell script of a binary executable that performs
batch operations every time a tomb is opened.
<P>
</DL>
<A NAME="lbAH">&nbsp;</A>
<H2>PRIVILEGE ESCALATION</H2>
<P>
The tomb commandline tool needs to acquire super user rights to
execute most of its operations: to do so it uses <A HREF="/cgi-bin/man/man2html?8+sudo">sudo</A>(8), while
<A HREF="/cgi-bin/man/man2html?1+pinentry">pinentry</A>(1) is adopted to collect passwords from the user.
<P>
Tomb executes as super user only those commands requiring it, while it
executes desktop applications as processes owned by the user.
<P>
<P>
<A NAME="lbAI">&nbsp;</A>
<H2>BUGS</H2>
Please report bugs on the tracker at <A HREF="http://bugs.dyne.org">http://bugs.dyne.org</A>
<P>
Get in touch with developers via mail using this web page
<A HREF="http://dyne.org/contact">http://dyne.org/contact</A> or via chat on <A HREF="http://irc.dyne.org">http://irc.dyne.org</A>
<P>
<A NAME="lbAJ">&nbsp;</A>
<H2>AUTHORS</H2>
<P>
Tomb is designed and written by Denis Roio aka Jaromil.
<P>
Tomb's artwork is contributed by Jordi aka Mon Mort
<P>
Testing and fixes are contributed by Dreamer and Hellekin O. Wolf
<P>
Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth
<P>
<A NAME="lbAK">&nbsp;</A>
<H2>COPYING</H2>
<P>
This manual is Copyleft (c) 2011 Denis Roio &lt;<I><A HREF="mailto:jaromil@dyne.org">jaromil@dyne.org</A></I>&gt;
<P>
Permission is granted to copy, distribute and/or modify this manual
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
Permission is granted to make and distribute verbatim copies of this
manual page provided the above copyright notice and this permission
notice are preserved on all copies.
<P>
<A NAME="lbAL">&nbsp;</A>
<H2>AVAILABILITY</H2>
<P>
The most recent version of Tomb sourcecode and up to date
documentation is available for download from its website on
<I><A HREF="http://tomb.dyne.org">http://tomb.dyne.org</A></I>.
<P>
<A NAME="lbAM">&nbsp;</A>
<H2>SEE ALSO</H2>
<P>
<B><DL COMPACT>
<DT><A HREF="/cgi-bin/man/man2html?8+cryptsetup">cryptsetup</A>(8)<DD>
</B>
<P>
GnuPG website on <A HREF="http://www.gnupg.org">http://www.gnupg.org</A>
<P>
DM-Crypt website on <A HREF="http://www.saout.de/misc/dm-crypt">http://www.saout.de/misc/dm-crypt</A>
<P>
LUKS website, <A HREF="http://code.google.com/p/cryptsetup">http://code.google.com/p/cryptsetup</A>
<P>
</DL>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">COMMANDS</A><DD>
<DT><A HREF="#lbAF">OPTIONS</A><DD>
<DT><A HREF="#lbAG">HOOKS</A><DD>
<DT><A HREF="#lbAH">PRIVILEGE ESCALATION</A><DD>
<DT><A HREF="#lbAI">BUGS</A><DD>
<DT><A HREF="#lbAJ">AUTHORS</A><DD>
<DT><A HREF="#lbAK">COPYING</A><DD>
<DT><A HREF="#lbAL">AVAILABILITY</A><DD>
<DT><A HREF="#lbAM">SEE ALSO</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 18:57:34 GMT, March 09, 2011
</BODY>
</HTML>

View File

@ -1,183 +0,0 @@
.TH tomb 1 "February 12, 2011" "tomb"
.SH NAME
Tomb \- the Crypto Undertaker
.SH SYNOPSIS
.B
.IP "tomb [options] command [arguments]"
.B
.IP "tomb-open [file]"
.B
.IP "tomb-status mountpoint"
.SH DESCRIPTION
Tomb is an application to manage the creation and access of encrypted
storage files: it can be operated from commandline and it can
integrate with a user's graphical desktop.
Tomb generates encrypted storage files to be opened and closed using
their associated keys, which are also protected with a password chosen
by the user. To create, open and close tombs a user will need super
user rights to execute the tomb commandline utility.
A tomb is like a locked folder that can be safely transported and
hidden in a filesystem; it encourages users to keep their keys
separate from tombs, for instance keeping a tomb file on your computer
harddisk and its key file on a USB stick.
For simplified use, the command \fItomb-open\fR starts a wizard that
guides users in the creation of a new tomb or, if a tomb file is
specified as \fIargument\fR, it opens it and makes it accessible in a
default location under the /media folder, starting the status tray
applet (\fItomb-status\fR) if a desktop is present.
.SH COMMANDS
.B
.IP "create"
Creates a new encrypted storage tomb and its key, named as specified
by the given \fIargument\fR.
.B
.IP "open"
Opens an existing tomb file specified in the \fIfirst argument\fR. If
a \fIsecond argument\fR is given it will indicate the \fImountpoint\fR
where the tomb should be made accessible, if not then the tomb is
mounted in a directory named after the filename and inside /media.
.B
.IP "close"
Closes a currently open tomb. When \fIan argument\fR is specified, it
should point to the tomb mount on /dev/mapper; if not specified and
only one tomb is open then it will be closed; if multiple tombs are
open, the command will list them on the terminal. The special
\fIargument\fR 'all' will close all currently open tombs.
.B
.IP "bury"
Hides a tomb key (\fIfirst argument\fR) inside a jpeg image (\fIsecond
argument\fR) using steganography: the image will change in a way that
cannot be noticed by human eyes and the presence of the key inside it
isn't detectable without the right password. This option is useful to
backup tomb keys in unsuspected places; it uses steghide and the
serpent encryption algorithm.
.B
.IP "exhume"
Extracts a named tomb key (\fIfirst argument\fR) from a (jpeg) image file
(\fIsecond argument\fR) known to be containing it, if the right password is
given. This is used to recoved buried keys from unsuspected places.
.SH OPTIONS
.B
.B
.IP "-s \fI<MBytes>\fR"
When creating a tomb, this option must be used to specify the size of
the new \fIfile\fR to be created, in megabytes.
.B
.IP "-k \fI<keyfile>\fR"
When opening a tomb, this option can be used to specify the location
of the key to use. Keys are created with the same name of the tomb
file adding a '.gpg' suffix, but can be later renamed and transported
on other media. When a key is not found, the program asks to insert a
USB storage device and it will look for the key file inside it.
.B
.IP "-n"
Skip processing of post-hooks and bind-hooks if found inside the tomb.
See the \fIHOOKS\fR section in this manual for more information.
.B
.IP "-h"
Display a help text and quit
.B
.IP "-v"
Display version and quit
.B
.IP "-q"
Run more quietly
.IP "-D"
Print more information while running, for debugging purposes
.SH HOOKS
Hooks are special files that can be placed inside the tomb and trigger
actions when it is opened and closed; there are two kinds of such
files: \fIbind-hooks\fR and \fIpost-hooks\fR can be placed in the
base root of the tomb.
.B
.IP "bind-hooks"
This hook file consists of a simple two column list of files or
directories inside the tomb to be made directly accessible inside the
current user's home directory. Tomb will use the "mount \-o bind"
command to bind locations inside the tomb to locations found in $HOME
so in the first column are indicated paths relative to the tomb and in
the second column are indicated paths relative to $HOME contents, for
example:
mail mail
.gnupg .gnupg
.fmrc .fetchmailrc
.mozilla .mozilla
.B
.IP "post-hooks"
This hook file gets executed as user by tomb right after opening it;
it can consist of a shell script of a binary executable that performs
batch operations every time a tomb is opened.
.SH PRIVILEGE ESCALATION
The tomb commandline tool needs to acquire super user rights to
execute most of its operations: to do so it uses sudo(8), while
pinentry(1) is adopted to collect passwords from the user.
Tomb executes as super user only those commands requiring it, while it
executes desktop applications as processes owned by the user.
.SH BUGS
Please report bugs on the tracker at http://bugs.dyne.org
Get in touch with developers via mail using this web page
http://dyne.org/contact or via chat on http://irc.dyne.org
.SH AUTHORS
Tomb is designed and written by Denis Roio aka Jaromil.
Tomb's artwork is contributed by Jordi aka Mon Mort
Testing and fixes are contributed by Dreamer and Hellekin O. Wolf
Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth
.SH COPYING
This manual is Copyleft (c) 2011 Denis Roio <\fIjaromil@dyne.org\fR>
Permission is granted to copy, distribute and/or modify this manual
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
Permission is granted to make and distribute verbatim copies of this
manual page provided the above copyright notice and this permission
notice are preserved on all copies.
.SH AVAILABILITY
The most recent version of Tomb sourcecode and up to date
documentation is available for download from its website on
\fIhttp://tomb.dyne.org\fR.
.SH SEE ALSO
.B
.IP cryptsetup(8)
GnuPG website on http://www.gnupg.org
DM-Crypt website on http://www.saout.de/misc/dm-crypt
LUKS website, http://code.google.com/p/cryptsetup