# $Id: cabot-micro-howto.txt 149 2004-07-01 08:16:35Z lfousse $

# Note:  Thanks to Stefan for taking the time and efford of writing this.  It's
#        not perfect and I do quite a few things different than he does, but as
#        long as it works, hey, that's great.
#
#        For instance I don't use sudo, but instead have ca's directories g+w
#        and me in the cabot group.
#
# Peter Palfrader


=================
Cabot Micro-HOWTO
=================

0. Legal stuff
==============
(c) Stefan U. Hegner <admin@hegners.net>, January 09, 2004
changed January 14, 2004 by Stefan U. Hegner <admin@hegners.net>

This piece of information is realeased together with CA Bot under the Gnu
Public License(GPL; V. 2 or later) to be found at
http://www.gnu.org/copyleft/gpl.html

1. Preface
==========
... since there is not much documentation about cabot around presently and
since it took me two days to get this thing running the way I want it to run,
here's what I did. - I hope others may benefit from this.

By the way, my system is Gentoo. - If you are running something different,
details may differ slightly.

In the following I assume that readers who want to use a CA Bot are at least as
Linux-literate that they know basic shell commands such as chown, chmod, ln,
and the like. I hope this assumption is apropriate.

Other software needed:
This depends very much on your needs and wants. I use the following:
- Postfix as local MTA
- Fetchmail to get external mail (only needed if you are on a non-internet
  domain)
- Sudo to run ca-recv as you normal user


2. Setup
========
The setup in Cabot breaks down in 3 Main steps:

- create user account and copy files (Install)
- set permissions and adjust config (Config)
- adapt mail transport (Mail config)

2.1. Install
============
The first thing you should do is to create a user account for your cabot user.
On Gentoo I did this by

mybox:/ # adduser -g users -d /var/cabot -s /bin/false -c CA-BOT cabot

In case you are running Debian and got their adduser package you may use

mybox:/ # adduser --system --home /var/cabot \
          --shell /bin/false --group users --disabled-password \
          --disabled-login --gecos "CA-Bot" cabot

Where the parameters have the following meaning:

	/var/cabot	The bot's homedir. You may change this according to your flavor
				and needs (e.g. if running multiple ca bots for different
				users)
	
	users		The initial group of cabot. Should be the same initial group as
				the normal user (=cabot owner) has. But this is no law, too.

	/bin/false	The login shell for the cabot user. During testing you may
				want to change this to /bin/sh in /etc/passwd (covered later).
				If set to /bin/false no login is possible.
	CA-Bot		The comment for the Username. Could be also something like
				"Bill's CA-Bot" ... Whatever makes sense to you
	cabot		The username for the cabot account. When using multiple
				cabots on one machine, you will need an account for each bot.

After this, you can check /etc/passwd for your entries. At the end of the file
there should be a line similar to this:

	cabot:x:1010:100:CA-Bot:/var/cabot:/bin/false

Now that you got your brandnew cabot account, you want to copy files there.
What I did was the following:

I created ~cabot/bin (drwxr-x--- cabot users) and placed there:
-rwxr-x---    1 cabot    users        6834 2003-09-08 22:18 ca-createsendout
-rwxr-x---    1 cabot    users       11204 2003-11-28 00:29 ca-dosign
-rwxr-x---    1 cabot    users        6507 2003-08-22 12:07 ca-recv
-rwxr-x---    1 cabot    users        9276 2004-01-07 18:22 ca-sendout

Note: The scripts normally create the needed directories themselves - I just
wanted to be on the safe side regarding rights & ownership.

All these commands will be run (at least in my setup) by the user "owning" the
cabot. Hence the group setting and the (r-x) attributes for the group are
important.

Next I created the four working directories in ~cabot as follows:
drwxrwx---    2 cabot    users        4096 2004-01-07 14:46 done
drwxrwx---    2 cabot    users        4096 2004-01-09 16:09 sendout
drwxrwx---    2 cabot    users        4096 2004-01-09 16:12 sent
drwxrwx---    2 cabot    users        4096 2004-01-09 16:15 tosign

After this, I took the cabotrc sample file and placed it also in the ~cabot
directory (/var/cabot in my case):
-rw-rw-r--    1 cabot    users        3500 2004-01-09 16:15 .cabotrc

Make sure it has the correct group of your normal user and it is group
readable.

The next (though non-mandatory) step is to set up a few symlinks for the ca-bot
scripts. I find it convenient, if I don't need to specify the full path when
invoking the scripts. I placed the links for my standard-user hegi in the
/home/hegi/bin directory:
lrwxrwxrwx    1 hegi     users          31 2004-01-09 11:38 ca-createsendout ->
/var/cabot/bin/ca-createsendout
lrwxrwxrwx    1 hegi     users          24 2004-01-09 11:39 ca-dosign ->
/var/cabot/bin/ca-dosign
lrwxrwxrwx    1 hegi     users          25 2004-01-09 11:39 ca-sendout ->
/var/cabot/bin

Note: ca-recv is only invoked on reception of mail and does not need to be
started manually. Hence I left out the link for this.

Of course you could alternatively simply install the binaries somewhere
globally - say /usr/local/bin or so - but I preferred having them only
accessible for the relevant users. All the stuff written here is neither law
nor recommendation - it's just my way of doing things.

Finally you should also create a symlink to the .cabotrc file in your home
directory:
lrwxrwxrwx    1 hegi     users          19 2004-01-07 14:35 .cabotrc ->
/var/cabot/.cabotrc

Make sure you can read this file. If you set write permissions for the group
for the original file (I found this convenient) you can now even edit your
.cabotrc as the std-user.

... congratulations. You just managed to complete phase 1

2.2. Config
===========
Now lets have a look at this .cabotrc file. Here are the things I found
important:

First you enter you Email Address and Name:
my $CONFIG_realaddress = 'my.standard@email.address';
my $CONFIG_fullname    = 'My Full Name';

The next is your PGP/GPG keyid (8 digits in HEX notation, e.g. 'ab98dd3d':
$CONFIG{'keyid'}       = '12345678';

If you want copies of your Bots outgoing mails, fill your local email address
here:
$CONFIG{'BCCmail'}     = 'user@localhost';

This field is what your CA Bot displays as Sender in Emails and the like:
$CONFIG{'bot'}         = $CONFIG_fullname . ' (CA BOT) <cabot@email.address>';

You should use here the "world" email address for your cabot. If you - like me
- dont't have a machine with a valid internet domain and if you get your mail
by polling accounts from a provider, get yourself a POP3 account for your cabot
from a provider of your choice and place its address here. How you get this to
work is covered in 2.3.

Here you put the homedir of your cabot user as defined way up above:
$CONFIG{'cabothome'}   = '/var/cabot';

In the keyserver section uncomment any keyservers of your choice. But since all
of them will be queried, I recommend to use only one or two.

Now you are basically done with the config. I personally did a bit more
(changed the email texts to German/English). If you want to change the
encrypted text as well, you need to edit ca-recv (but you better keep a copy of
the original before you do that).

Finally you may want to change
$CONFIG{'sendmail'}    = '|/usr/lib/sendmail -t';

to
$CONFIG{'sendmail'}    = '|cat';

for testing purposes. Of course the sendmail command also needs to work and to
be in the place specified ...

Congratulations. You just finished step 2.

2.3. Mail config
================
Now you need to make cabot handle emails properly. First you want to be able to
send out mails. If you got all your data in the .cabotrc right this should
already work, provided your local MTA is configured to relay mail to some
mailserver.

If this is not the case, you need to study the docs of your MTA (postfix,
sendmail, whatever) and configure it accordingly.

But since we currently use  the test setting, it won't matter at the moment.
	$CONFIG{'sendmail'}    = '|cat';

The next step is to make sure, cabot can receive email. If you local cabot
email-address (e.g. cabot@your.box.com) is a valid internet email address and
your mailserver is configured to accept internet mail for local users, you are
probably fine.

However, if you - like me - make use of some external mailserver that you
access locally by POP3 or IMAP you need to configure fetchmail or something
similar. A short sample /root/.fetchmailrc could look as this:

	defaults
	flush
	no keep
	fetchall
	
	poll my.email.provider with proto pop3:
		user my.cabot.email.login there has password "cabot-email-password"
		and is cabot here;

Where

	my.email.provider	is your providers pop3 server
	my.cabot.email.login	your login for the email account used by cabot
	cabot-email-password	the password for the above mentioned account
	cabot			the local username for the cabot user

Now you can add a line in your crontab (by issueing crontab -e as root) like
this:

	0,15,30,45 8-20 * * *         /usr/bin/fetchmail > /dev/null

to check automatically for mail (here: every 15 minutes from 8:00am til
20:45pm)

Note: of course you can run cron also as "cabot" user. I fetch mail for a bunch
of accounts and I'm used to do this as root.

Note: The next section is somewhat controversial. Using sudo is a security
risk! - But again, this is my way of doing things (and I'm not an expert). If
you got good ideas how to accomplish this in a better alternative way, please
let me know.

But now comes the tough bit (looks easy though - but it was a long way till I
figured this out and got it working) - cabot needs to get fed with incoming
mails.

First I edited the sudoers file (as root) using visudo and added one line:

nobody  mybox = (hegi) NOPASSWD: /var/cabot/bin/ca-recv

This allows the user nobody (by whom postfix delivers the mail on Gentoo) to
run the ca-recv (check path) script as the user "hegi" (your normal user here)
with all relevant permissions without specifying a password. - This is a (small
though) potential security loophole.

Next you need to tell your MTA to pipe mails to the cabot user through ca-recv
(while running as your std-user). A common way for this would be procmail. But
since I don't use procmail and I didn't want to install it just to run a cabot
I found another way:

After lots of unsatisfying tries I edited my /etc/mail/aliases (may be
/etc/aliases on your system) and added the following lines:

	# pipe mails to cabot through ca-recv
	cabot:   | "/usr/bin/sudo -u hegi /var/cabot/bin/ca-recv"

Now, whenever a mail is sent to the local user cabot ca-recv is invoked with
the permissions of your std-user, the mail gets processed and you are done. If
you want (e.g. for debugging) to get a copy of these mails, add your local
username to this line seperated by a space (and run newaliases again).

Now there are two alternatives doing this. If yo don't want to use aliases for
this, you may create a .forward that does this job by issuing

mybox:/ # echo "| /usr/bin/sudo -u hegi /var/cabot/bin/ca-recv" >
 /var/cabot/.forward

or you can use the "mda" keyword in your .fetchmailrc Then you say:

	poll my.email.provider with proto pop3:
		user my.cabot.email.login there has password "cabot-email-password"
		mda "/usr/bin/sudo -u hegi /var/cabot/bin/ca-recv"

Note: However, I havn't had a chance to test these last two alternatives yet.

In theory you are done now!

3. Testing
==========

Login as your normal user and do the following:

hegi@mybox:~ > ca-createsendout [some keyid you want to sign, e.g. 12345678]

Answer yes when you get prompted whether you want to create a sendout for that
id after it has been found on a keyserver. Next do:

hegi@mybox:~ > ls -l ~cabot/sendout

You should see a directory named after the keyid specified. Now you want to

hegi@mybox:~ > ca-sendout >testfile.gpg

Since you have the |cat in your .cabotrc (as described above) no email is sent,
but a file created. Browse it, to see how it looks like. This file contains the
encrypted challenge to that user. If you (as I recommended) put your keyid in
the .cabotrc, you can now decrypt that mail as well by

hegi@mybox:~ > gpg -d testfile.gpg > testfile

Enter your passphrase and browse the decrypted testfile with a viewer of your
choice. Now do

hegi@mybox:~ > ls -l ~cabot/sendout

The dir should be empty again. But if you do a

hegi@mybox:~ > ls -l ~cabot/sent

you should find a dir named after the keyid you are testing.

Now email the contents of testfile (or at least the three lines with the
challenge, looking like this

| Key: 12345678
| Magic: 96E6320B1D77E19D23AF1A1C3A2CAF378A739488E86FD16D
| Upload to keyservers: Yes

to your cabot account. If all works fine

hegi@mybox:~ > ls -l ~cabot/sent

returns an empty dir, but the keyid is shown when typing

hegi@mybox:~ > ls -l ~cabot/tosign

Now you can theoretically sign that key. Before proceding any further do a

hegi@mybox:~ > rm -rf ~cabot/tosign/*

to remove your test-data. Change the transport in the .cabotrc back to

	$CONFIG{'sendmail'}    = '|/usr/lib/sendmail -t';

or whatever suits your needs.

Now you can run ca-createsendout and ca-sendout for real. Provided you have
setup outgoing email in the meantime (if not setup already on your system).
When you receive a completed challenge back, you get an email notification,
provided you filled the $CONFIG{'BCCmail'} in your .cabotrc. Once the callenge
is back you can sign the key(s) using ca-dosign.

... That's all.

4. Troubleshooting
==================
There are millions of ways to find and elimate possible errors on the way. I'm
more a user than a developer, here are some things I had to check and correct
on my way:

- If ca-createsendout and ca-sendout don't create and move data files as
  described in Section 3, your normal user probably has not the correct rights
  for the data directories.

- If the data doesn't get moved on receving the email with the challenge back
  from sent to dosign directory, your problem is one of the folling:

	- email communications
	- local email transport
	- wrong rights or uid for ca-recv

For the email stuff consult your logs (syslog, maillog ... whatever). My
postfix reports the sender, when having problems delivering the mail. This
error may also be helpful. You can also "dryrun" ca-recv, by piping the text
with the challenge to it. E.g. by

	hegi@mybox:~ > ca-recv < testfile

  in the procedings of 3. instead of sending an email.

... but as said before: I'm not an expert. This is only my 2 cents to cabot by
typing down what I did. - Hope this is helpful.

### END.
