 __  __     _ _   _   ____ _ _
|  \/  |___(_) | / \ | .__(_) |___
| \  / / _ | | |/ = \|  _|| | | o_)
|_|\/|_\_,_|_|_|_/ \_|_|  |_|_|___| 0.21, 4 December 2002

Written by Darren Salt


Requirements
============

 * Newsbase 0.60 or later, MsgServe, MsgServeS or RemoteNB;
 * PGP or GnuPG, for signing and encrypting.


How to use
==========

MailAFile will uuencode and mail a file for you. It will also, optionally,
clearsign the file.

It is important to note that it's the original unencrypted file for which the
signature is generated, and *not* the uucode. This means that the signature
can be used by the recipient(s) to check the file after decoding (and
decrypting, if necessary), and can store the signature along with it -
potentially useful for ftp sites and the like.

The MailAFile iconbar icon has five states:

 * Grey closed envelope
   - unavailable because no server (eg. Newsbase) is running.

 * Grey open envelope
   - no user logged in.

 * Open envelope
   - logged in. You may drag a file to it.

 * Open envelope with archive icon
   - logged in, file to be sent.

 * Closed envelope
   - busy sending the file.

The first two states also show the text "MailAFile"; the rest show the ID of
the currently logged-in user.


Logging in
----------

If you have a default user configured for Messenger Pro, Messenger or TTFN,
then MailAFile will do an automatic login for you, running the server if
necessary. You will not be asked for a password; consequently, if a password
is required for the user ID, then if it has been changed or none can be
supplied by the mailreader config, then automatic login will fail.

Otherwise, you'll have to log in yourself via the iconbar icon's "Log in"
submenu. If your chosen user ID is password protected, you will be prompted
for the password.

If no submenu is available, then no server is running; click instead on the
"Log in" menu entry to run one. (Currently, it just runs the first available
server, defaulting to Newsbase then, if Messenger is detected, to MsgServe.)

Note that you cannot open the iconbar menu while the server is starting up.


Logging out
-----------

Either quit the server or select the "Log out" menu entry in the iconbar
menu.


Sending a file
--------------

To send a file, drag it to the MailAFile icon. This will cause the 'Send'
window to be opened: this window displays the filename, and has three
writable fields for email addresses, one for the subject line, and one for
a reply-to address. You'll see that a default subject is already entered for
you.

(You can change which file is sent by dragging a different one to the icon or
to the Send window.)

The To, Cc and Bcc fields have menu icons; click on one of these to open your
address book, then on an address book entry to add it to those addresses
already present. If the 'address' is a distribution list, then it will appear
preceded by '#' (it will be expanded later). (Note that the aliases supported
by Messenger are not recognised.)

You can drag selections from text files to any of the writable fields in this
window, or press Ctrl-V to paste from the global clipboard. The normal action
is to append; holding down Shift will cause the field's contents to be
overwritten instead.

(There is a 240-character limit on the total length of the addresses in each
field; if adding the selected address would exceed that, you'll hear a beep.)

There are also the following options:

  Sign
        Tick this if you want to clearsign the file.

  Encrypt
        Tick this if you want to encrypt the file; this causes the
        filename (as it appears in the uucode) to have ".pgp" or ".gpg"
        appended. If you do not have a public key for each intended
        recipient, then the file cannot be encrypted and sent.

  PGP
  GnuPG
        Use the selected program for signing and encryption.

  Append filetype
        Tick this if you want the filetype to be appended to the filename in
        the uucode. It will be ticked automatically if the file's leafname
        does not include a '/'. (The format used is "file,ffd",
        "file.pgp,ffd" or "file.gpg,ffd" where ffd is the filetype.)

  Split
        Tick this if you want the uucode to be split into chunks, the size of
        which can be set by using the arrow icons to the right of the chunk
        size display field (Shift-click for 10K steps). Useful if there's a
        message size limit to avoid :-)

The signing and encryption options will be unavailable if MailAFile thinks
that you have neither PGP nor GnuPG.

(For further information on the writable fields in the 'Send' window, see the
part of your mailreader's documentation concerned with sending mail.)

To proceed to the next stage, click on OK or press Return. If you haven't
entered at least one destination address, then you must do so first; if the
subject line is blank, then the default one will be used.

The order of actions is as follows (some steps may be omitted; if a step
fails, you'll be returned to the send window):

  If encrypting, create an encrypted copy of the file
  If signing,
    Ask the user for the pass phrase
    Create the signature for the unencrypted file
  UUencode the file, using the encrypted form if present
  If signing, append the signature
  Tell the server to send the message(s)

No local copy of the message is stored. So don't go looking in your
outgoing.mail folder for it :-)


Encrypting the file
-------------------

You *must* have a public key for each recipient, else MailAFile will not let
you encrypt the file.

Be sure to specify as much of the address as is required to uniquely identify
a public key, since each address in the To, Cc and Bcc fields (distribution
list names are expanded to lists of addresses) is passed to PGP or GnuPG: eg.
if the 'To' field contains "foo <foo@here>, bar@there" then both "foo
<foo@here>" and "bar@there" will be used.


Signing the file
----------------

If you have chosen to sign the file, then you will be prompted for your pass
phrase unless you have already entered one since logging in and chosen to
retain it by ticking 'Remember until logout'.

(Without the Sign option selected, you will not be asked for your pass
phrase and the file will not be signed.)

When you've entered your pass phrase, either press Return or click on OK;
MailAFile will then run PGP or GnuPG. If all goes well, the signature will be
generated and the file sent.

If you entered an incorrect pass phrase, or the private key can't be found,
MailAFile will inform you that it couldn't sign the file, and the send window
will be reopened with the PGP option deselected.

You can, if you wish, leave the pass phrase field blank; in this case, PGP pr
GnuPG will be run in a task window and will ask for your pass phrase. (If the
private key can't be found, you may be asked for the filename of the private
keyring; you should probably press Escape unless you actually *do* have a
differently-named keyring.) Aborting this operation will cause the above
"couldn't sign" behaviour.


Sending the file
----------------

All automated.


Future improvements
===================

- GMail support?


Contact
=======

ds@youmustbejoking.demon.co.uk
