<!DOCTYPE Book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">

<book>
  <title>Quintuple Agent</title>
  <bookinfo>
    <author>
      <firstname>Robert</firstname>
      <surname>Bihlmeyer</surname>
    </author>
  </bookinfo>
  <chapter>
    <title>Introduction</title>
    <para>
Quintuple Agent is a program that stores secrets for you.</para>
    <para> 
An example usage of Quintuple Agent would be for the storage of a passphrase.
This way you will have to enter the passphrase only once in a while, not
everytime it is needed.</para>
  </chapter>
  <chapter>
    <title>Building Quintuple Agent</title>
    <para>
Quintuple Agent requires glib (a library of generic C functions). For more
information on glib, see <ulink url="http://www.gtk.org/"></ulink>. Download locations are
listed in <ulink url="ftp://ftp.gtk.org/etc/mirrors"></ulink>.
</para>
    <para>
The GTK+ library (available from the same location as glib) is needed for some
convenient functionality (including secret-on-demand).
</para>
    <para>
To use internationalization (i18n), Quintuple Agent needs a usable gettext or
catgets implementation. If your system does not provide one (e.g. HP-UX),
either use the configure switch "&ndash;-disable-nls", or get GNU gettext from
your nearest GNU mirror (a list of mirrors is available under
<ulink url="ftp://ftp.gnu.org/gnu/GNUinfo/FTP"></ulink>).
</para>
    <para>
General installation instructions are given in the file "INSTALL". In short:
"./configure; make install" should work.
</para>
    <para>
Quintuple Agent is developed on Intel GNU/Linux. All in all, it has been
successfully tested on:
</para>
    <para>
<itemizedlist>
	<listitem><para>Intel GNU/Linux Debian 2.2</para></listitem>
	<listitem><para>Sparc SunOS 5.8 (a.k.a. Solaris 2.8)</para></listitem>
	<listitem><para>Intel FreeBSD 4.3</para></listitem>
	<listitem><para>HPPA HP-UX 10.20 [1]</para></listitem>
      </itemizedlist>
</para>
    <para>
Previous versions compiled correctly on the following platforms, but their
current status is unknown:
</para>
    <para>
<itemizedlist>
	<listitem><para>Alpha Digital Unix 4.0</para></listitem>
	<listitem><para>Alpha GNU/Linux RedHat 5.2</para></listitem>
	<listitem><para>Intel GNU/Linux RedHat 4.2 (libc5)</para></listitem>
	<listitem><para>DEC Ultrix 4.3</para></listitem>
      </itemizedlist>
</para>
    <para>
[1] I needed to add &ndash;-with-included-gettext to the configure call to
compile cleanly.
</para>
    <para>
It should run on almost any Unix-like platform with only minor modifications.
Please send me mail, if you get it to run on a system not mentioned above.
</para>
  </chapter>
  <chapter>
    <title>Using Quintuple Agent</title>
    <para>
Before the agent will do anything for you, you'll have to start it like this:
</para>
    <para>
$ eval `q-agent &`
</para>
    <para>
(This is for a bourne-compatible shell, c-shell users will have to add a
"&ndash;-csh" option to the call.) What this does is start q-agent in the
background. It will print commands to stdout that set $AGENT_SOCKET. The
"eval" catches, and executes those.
</para>
    <para>
From now on, you can talk to the agent by means of the q-client. Let's do 
something useful, like storing a secret:
</para>
    <para>
$ q-client put 12345678 "Alice Manners"
</para>
    <para>
The client will respond by asking you for the secret. (Enter something, but
don't enter a real secret, yet.) This secret will be stored with the agent
under the tag "12345678". The last argument is a comment, that can hold
additional information about the secret. It is not used yet, and you can just
leave it out. Secrets can be retrieved later with the `get' command, something
like this:
</para>
    <para>
$ q-client get 12345678
</para>
    <para>
To protect the innocent, q-client will refuse to output the secret
directly. If you didn't use a real secret, you can append "| cat" just for
testing. This will fool "q-client" into printing your secret. DO NOT use
this trick with real secrets!
</para>
    <para>
Normally you'd pipe the output of this command into another application that
wants to read a password/passphrase on stdin. This way, the secret is never
shown to you (or, more importantly, shoulder-surfers).
</para>
    <para>
You should be aware, though, that your secret is simply available with a
single command. Keep this in mind, when you leave your terminal - you may
prefer locking it with vlock, xlock, xscreensaver, or something similar. If
others know the password to your account, or you don't trust root, you should
also be very wary. On the other hand, normal Unix semantics will protect your
secret from other (non-root) users on the same system.
</para>
    <para>
If, at a later stage, you decide that Quintuple Agent should forget your secret
(for example, because you leave your computer unattended for a while), just
issue:
</para>
    <para>
$ q-client delete 12345678
</para>
    <para>
which will wipe out the secret from memory.
</para>
    <para>
The main use for Quintuple Agent at the moment is the storage of GnuPG or PGP
passphrases. Of course you must have one of these programs to use it that way,
but I guess that is just the reason you downloaded Quintuple Agent.
</para>
    <para>
Support for GnuPG and PGP comes in the guise of so-called "wrappers", small
programs that you call instead of the real thing. The wrappers call the real
programs underneath, intercepting or anticipating passphrase requests.
Passphrase are fetched from the agent rather then entered every time by you.
Other than that, the wrappers try to look exactly like the underlying program.
</para>
    <para>
In that way, you can, for example, sign a lot of e-mails with gpg, and only
input the passphrase once.
</para>
    <para>
I will describe the usage with GnuPG first: Instead of calling "gpg", you will
run the agent wrapper called "agpg". For example, clear-signing the file "foo"
will work like this:
</para>
    <para>
$ agpg &ndash;-clearsign foo
</para>
    <para>
You will see that gpg wants a passphrase, but "agpg" will take care of that.
Other interaction with "gpg" works like usual.
</para>
    <para>
If you want to use PGP, the usage is similar. Calls to "pgp" are replaced by
calls to the agentized "apgp". Again, clear-signing the file "foo" is easily
done like this:
</para>
    <para>
$ apgp -sat foo
</para>
    <para>
The passpharse will be provided by "apgp", other questions will have to be
answered as usual.
</para>
    <para>
Note that only PGP 2.6.3 is supported at the moment. Other 2.6 versions may
work, but PGP 5.0 and higher will not.
</para>
    <para>
To use these wrappers effectively, Quintuple Agent must of course know your
passphrase. It can learn of your passphrase in two ways:
</para>
    <para>
(a) On demand
Provided that you have started "q-agent" with $DISPLAY set (i.e. from
inside X), the agent will automatically query you for any unknown secrets.
That means that the first time you use a wrapper, a window will pop-up, asking
you for a secret. You should enter the corresponding passphrase there. Further
usages of the same key will re-use this passphrase, until you kill
"q-agent", or delete the secret from its memory. Invoking a wrapper
instructing it to use new key (e.g. you have a RSA and a DSA key) will of
course ask for the new passphrase.
</para>
    <para>
(b) Before use
If you wish, you can also store your passphrase with Quintuple Agent before it
is used. This is the only way, if you start "q-agent" from outside X.
</para>
    <para>
The tag has to be your key id. If you don't know your id, for GnuPG, do:
</para>
    <para>
$ gpg &ndash;-list-secret-keys
</para>
    <para>
Find the line that starts with "sec". The number following the slash is your
key id. For example:
</para>
    <para>
sec  1024D/D415FC97 1999-08-05 Robert Bihlmeyer (DSA Testkey)
</para>
    <para>
Here the key id is "D415FC97". So I would store my passphrase like this:
</para>
    <para>
$ q-client put D415FC97 "passphrase for my DSA testkey"
</para>
    <para>
You should of course substitute your own key id, and a suitable comment,
there.
</para>
    <para>
For PGP, try listing all the keys matching your name, find the right one, and
again look after the first slash (the column is titled "KeyID"). I would do:
</para>
    <para>
$ pgp -kv "Robert Bihlmeyer"
</para>
    <para>
one of the resulting lines reads:
</para>
    <para>
pub   512/5F570039 1999/10/19 Robert Bihlmeyer (RSA Testkey)
</para>
    <para>
which makes "5F570039" my key id. I will store it as above.
</para>
  </chapter>
  <chapter>
    <title>Going Further</title>
    <para>
There are a few knobs you can twiddle to suit "q-agent" more to your
needs.
</para>
    <para>
One important setting that can be made at the initial deposition of a secret
is the time it will be remembered. The default is to remember it for an
indefinite timespan: until the daemon dies, or you manually invoke the
deletion. You are also free to select a maximum lifetime for the secret. After
the passage of the given number of seconds, "q-agent" will remove all
traces of the secret from its memory. The time-to-live can be set with the
"-t" option to "q-client put". For example,
</para>
    <para>
$ q-client -t 600 put 1234
</para>
    <para>
will give the "1234" secret a maximum lifespan of 10 minutes. If the daemon
still runs by then, and the secret has not been deleted manually, it will be
deleted automatically.
</para>
    <para>
It is also possible to mark certain secrets so that "q-agent" will only
hand them out after asking for permission. This confirmation requests consists
of a small pop-up window (so this will only work if "q-agent" was started
from within a windowed environment), which states the ID and comment of the
secret, and asks whether it is ok to give it out or not. Unless you answer the
question affirmatively, the secret is not handed out. To turn this behaviour
on, add "-i" to your "q-client put" request. For example,
</para>
    <para>
$ q-client -i put 5678
</para>
    <para>
will instruct "q-agent" to insure itself of your permission before ever
giving out secret "5678". The "-i" and "-t" options may be freely mixed.
</para>
    <para>
This does not buy you that much more security, but it prevents simplistic
attacks, where someone breaks into your (or root's) account, and just calls
"q-client get" to spy on your secrets. But even with insurance, there are
ways for an attacker to get the secrets, *if* she is able to gain access to
your or root's account at the time you have the secrets stored inside
"q-agent".
</para>
  </chapter>
  <chapter>
    <title>Security</title>
    <para>
Since Quintuple Agent is meant to store sensitive information, it is prudent to
ponder the security of that information. Is it safe from prying eyes?
</para>
    <para>
First off, let's restate two assumptions:
</para>
    <para>
<itemizedlist>
	<listitem><para>It's senseless to hide information from yourself. The
	main point of Quintuple Agent is to provide ready access to your
	secrets for processes running under your user id.</para></listitem>
	<listitem><para>Hiding information from priviledged users (root) makes
	no sense. There are a lot of ways how root could get at your
	secrets. If you don't trust your administrator, you should not
	use your account.</para></listitem>
      </itemizedlist>
</para>
    <para>
A direct consequence is that your secrets are in danger from an attacker that
has access to your or root's account at the moment q-agent holds the
secret. So don't leave your terminal unguarded while q-agent is hoarding 
secrets. One second would be enough for some bystander to learn your secrets.
</para>
    <para>
BUT: an attacker gaining access to your or root's account after a secret has
been erased from q-agent's memory will not get any information about
that secret.
</para>
    <para>
To attain this goal, all included tools handling secrets take some pains to
erase them as soon as they are no longer needed. Even for attackers with
hi-tech equipment it is a considerable task to reconstruct overwritten
information in RAM.
</para>
    <para>
Disk storage is another thing: once a bit pattern is written to disk, it may
stay there an indefinite amount of time (regardless of the "free" status of
the block containing it). There are known techniques to get at information
that was stored on disk, even if it was overwritten a few times. The tools
never write secrets to disk, and of course you should also refrain from doing
this.
</para>
    <para>
A problem case is paging, the action with which the operation system frees up
some RAM by writing pages that haven't been in use for some time to disk. In a
typical scenario you'd start up q-agent, store a passphrase there for
later use, and do different things in the meantime. Your clever OS sees that
q-agent is idle, and doesn't actually use its memory. When it gets short
of memory (or just for kicks), it will try to page out unused stuff, the area
where your secret is stored being a seemingly ideal candidate. We want to
prevent that.</para>
    <para>
First, if your operating system uses encrypted swap, you get in for free.
Everything written to disk will be useless to attackers that come by later.
You can page out sensitive data at will. Personally, I consider encrypted swap
the easiers, but not the optimal solution. Most of the data eligable for
paging is not that sensitive &ndash; e.g. the buffer contents of an editor
will probably end up on disk anyway, encrypting them while they are unsaved is
a waste of resources. Ideally, we would want only some of our data to not hit
the disk in cleartext.
</para>
    <para>
mlock() is a simple system call that achieves that: it prevents memory areas
from being paged out. The problem is that some systems don't support it at
all, while others only allow root to do this kind of thing. The tools which
want that kind of secure (read: mlock()ed) memory will give you appropriate
warnings in case it could not be provided. The first case can't be helped, but
for the second case there are two possibilities:
</para>
    <orderedlist>
      <listitem>
    <para>
Make the tools setuid-root. That will give them root privileges, so that
mlock() is not a problem. All tools in need of secure memory try to carfully
drop all privileges as soon as it is allocated. But I can't guarantee that
they work flawless, and a bug here could ruin your whole system's security.
Therefore I don't recommend this. If you still want to risk it, a viable
middle ground is to only make q-agent (which holds secrets for longer
durations) setuid-root, while leaving the other tools (which have considerably
shorter life-spans, so paging is much less probable) as-is, without secure
memory.
</para>
      </listitem>
      <listitem>
	<para>
Give the tools the `cap_ipc_lock' capability. This is actually a refinement 
of the first solution. Some systems support the notion of capabilities (also
known as "privileges"), which are a kind of "split-up root". If you manage to
grant a capability that allows for use of mlock() to the programs, they will 
use it to allocate secure memory. This is preferable to making them
setuid-root, because this capability has much less potential than the whole
bunch of root privileges. The only exploit, that I can think of, offhand, is
trying to mlock() as much memory as possible, to create a denial of service
situation.
</para>
      </listitem>
    </orderedlist>
    <para>
The only OS where this is known to work is Linux. You'll need:
</para>
    <para>
<itemizedlist>
	<listitem><para>a kernel that supports filesystem capabilities -
<ulink url="http://linux.kernel.org/pub/linux/libs/security/linux-privs/kernel-2.2-fcap"></ulink> has patches (the 2.2.16 patches worked well for me). The README there
  should explain things in detail.</para></listitem>
	<listitem><para>libcap, to link to the binaries</para></listitem>
	<listitem><para>the setcap program, included with libcap (you may need
	to get the newest version from CVS - libcap-1.10 is not new
	enough)</para></listitem>
	<listitem><para>the Quintuple Agent binaries prepared with "setcap
	cap_ipc_lock+p &lt;binary&gt;" (the installation procedure
	will try to do that automatically, if it can find the setcap
	binary)</para></listitem>
	<listitem><para>the binaries on a filesystem that supports extended
	attributes - to my current knowledge this includes only ext2 -
	AND mounted with the "cap" option or else the previous step
	will not work</para></listitem>
      </itemizedlist>
</para>
    <para>
Older patches at the linux-privs site offered an fcap-module - they worked as
follows: The kernel had to be patched, CONFIG_VFS_CAP_PLUGIN enabled, and
fcap-module loaded. Unfortunately, fcap-module was just a stopgap solution and
lost all settings on shutdown. So you'd have to repeat the "setcap" call above
after every reboot. Because of that I suggest that you upgrade to the newer
kernel patches described above if at all possible.
</para>
    <para>
All patches and sources should be available at
<ulink url="http://linux.kernel.org/pub/linux/libs/security/linux-privs/"></ulink>.
</para>
    <para>
</para>
  </chapter>
  <chapter>
    <title>Contact Information</title>
    <para>
Quintuple Agent's main distribution point is located at
<ulink url="http://www.vibe.at/tools/q-agent/"></ulink>
</para>
    <para>
Any mail concerning Quintuple Agent should be directed to
<email>robbe+sa@orcus.priv.at</email>.
</para>
  </chapter>
</book>
<!--
local variables:
fill-column: 78
end:
-->