Overview of gAIMgw
------------------

This package is distributed under the GNU General Public License.  See
COPYING for details.

This package is a gateway server to allow Gale users to send and receive
messages with their AOL Instant Messenger accounts.

For more information on gAIMgw, see <http://www.litech.org/gaimgw/>.

For more information on Gale, see <http://www.gale.org/>.


Installation overview
---------------------

1.  Install the gAIMgw package.
2.  Create a private/public keypair for the gateway.
3.  Create a configuration directory.
4.  Put username/password files into the configuration directory.
5.  Have each user create a buddy list using a Gale client.


Installing gAIMgw
-----------------

Before you begin, please make sure you have at least Gale version 0.99
installed.  Previous versions are known to have bugs that may prevent
gAIMgw from compiling or running properly.

First, compile and install the package.  Use:

./configure
make
make install

Now you need to decide what username you will run the server as, and
what Gale ID you will use to interact with Gale users.  I recommend
running the server as the same user as galed and gdomain.  Definitely
don't run it as root; it certainly doesn't have any need for root
privileges.  For the Gale ID, I recommend using gaimgw@<domain>,
but you may name your gateway whatever you wish.

Create the Gale keys by doing the following with an account that
has access to the private key for the domain (probably root).  Replace
"gaimgw" and "gale.gale" with the Gale ID and user/group you decided
on in the previous paragraph.

gkgen -r /usr/local/etc/gale/auth/private/gaimgw@<domain> \
  -u /usr/local/etc/gale/auth/local/gaimgw@<domain> gaimgw 'gAIMgw service'
chmod gale.gale /usr/local/etc/gale/auth/local/domain@<domain>
chmod gale.gale /usr/local/etc/gale/auth/private/domain@<domain>

gAIMgw needs to have a directory in which to store account information.
This directory is named "gaimgw" and is a subdirectory of the Gale system
directory (probably /usr/local/etc/gale).  Make sure this directory is
*only* readable by the user that gaimgw runs as, since it contains
buddy lists and AIM passwords in (essentially) cleartext!  Create with
something like the following:

mkdir /usr/local/etc/gale/gaimgw
chmod 700 /usr/local/etc/gale/gaimgw
chown gale.gale /usr/local/etc/gale/gaimgw

At this point, go ahead and fire up the gaimgw process.  Something like

su -c '/usr/local/sbin/gaimgw' gale

should do just fine.


How gAIMgw works
----------------

gAIMgw works by making a connection to AOL's AIM servers on behalf of each
user that it is configured for.  By listening to presence messages in the
@<domain>/notice/ category, gAIMgw determines whether there are any
clients for a particular user online.  When gAIMgw detects that a user
starts a Gale client (and none were running before), gAIMgw retrieves the
user's AIM username, AIM password, and buddy list from a file in its
configuration directory and makes a connection to AOL's AIM servers on
behalf of the user.  Then gAIMgw forwards messages from AIM to the
user's private Gale category, and forwards messages in the category
@<domain>/aim/<AIM user>/ to the AIM user specified in the category name.

If the status of an AIM buddy changes, for example from offline to
online, or online to unavailable, gAIMgw sends an appropriate presence
notice to the Gale user's private category.  If gAIMgw receives a
presence message that indicates that the Gale user has closed a Gale
client and no other clients for that user are running, then gAIMgw
closes the connection it has made to the AIM server for that user.


Using and maintaining gAIMgw
----------------------------

Anybody wanting to use the gAIMgw gateway needs to have a file created
in the configuration directory (probably /usr/local/etc/gale/gaimgw)
named with their fully-qualified Gale ID (user@domain).  This file
should contain a single line with the user's AIM name and "roasted"
password, separated by a colon.  No whitespace is allowed.  The
"roasted" password can be generated with the gaimgwpasswd utility
included with this package.  This roasting is trivial XOR masking
to hide the password, and is extremely simple to reverse.  Treat
the roasted password as if it were cleartext!  This is definitely
insecure, but it's how the AIM protocol was written.  As such, it
would be best to ensure that the configuration files are readable
only by the user that gaimgw runs as.  gAIMgw must also be able
to write to this file, since the file stores the user's buddy list.

Once this file is created, the user should be able to start a Gale
client and gAIMgw will establish a connection with the server.  Note
that once gAIMgw discovers that a user is online for the first time,
it will "ping" the user to determine whether there are any clients
running for that user that have not sent presence messages since
the gaimgw daemon was started.

Messages may now be exchanged between Gale and AIM.  Gale users may
send messages to the category @<domain>/aim/<AIM user>/ to send to
the AIM user specified in the category.  (The trailing slash on the
category is required!)  These messages must be encrypted for the
Gale ID of the gAIMgw, usually gaimgw@<domain> depending on how the
package was installed.

For Gale users to see presence messages for AIM users, they must add
the AIM users to their "buddy list", which is maintained by gAIMgw.
This is accomplished by sending messages containing commands to
@<domain>/aim/ encrypted for gaimgw.  Multiple commands may be
specified per line.  The commands are:

+<AIM user> (e.g. "+foo")
	Add a user to your buddy list
-<AIM user> (e.g. "-foo")
	Remove a user from your buddy list
?
	Retrieve a list of your buddies

After executing any of these commands, gAIMgw will send back a message
containing the current list of buddies for the user.  The buddy list
is maintained in the gAIMgw configuration file for the user.

-----------------

If you have any problems, please email me at <lutchann@litech.org> or
contact me via Gale.