NAME

       macutil, sendmac - Message Authentication Code utility

SYNOPSIS

       macutil --gen [options]

       macutil --sender [template] [--from name] [options]

       macutil --check [options] code

       macutil [options] --sendmail [sendmail-options]

       sendmac [sendmail-options]

DESCRIPTION

       macutil generates and checks the validity of codes that can be embedded in temporary email
       addresses.  The codes are calculated using a secret passphrase stored in a file.  Thus,
       someone who does not know the passphrase cannot easily generate a valid code.  Each code
       has a configurable expiration time after which it becomes invalid.

       To use macutil, you must create a file containing a passphrase.  The default location of
       this file is $HOME/.avenger/.macpass, though the location can be overridden with the
       MACUTIL_PASSFILE environment variable or --passfile= command-line option.  The file should
       contain a passphrase followed by a newline.  The maximum allowed length of the passphrase
       is 64 characters.  Do not use your Unix login password or any password you have used for a
       sensitive application, as macutil's password will be stored in cleartext and thus be
       relatively easy to compromise.

       Running macutil --gen generates a new code and writes it to standard output.

       Running macutil --check code checks the validity of code.  If the code is valid and has
       not expired, macutil exits with status 0.  If the code is invalid or has expired, macutil
       prints a message to standard error and exits with a non-zero exit code.

       The following options affect macutil's behavior:

       --gen (-g)
           Generates a code, as described above.

       --sender template (-s template)
           This option is like --gen, but outputs a complete email address, instead of just a
           code.  The address is formatted based on template.  template should contain an email
           address with a "*" character.  The "*" will be replaced by a code.  For example, if
           template is "myname+bounces+*", running "macutil --sender" might output:

               myname+bounces+zjkifk8kuvsy7rubu7vqadmwnn

           Don't forget to quote the "*" character when invoking macutil from a shell.

       --from name (-f name)
           This option, in conjunction with --sender, produces output more suitable for the
           "From:" field in an email message header.  For example, if name is set to "Mail
           Avenger", running "macutil --sender 'myname+tmp+*host' --from 'Mail Avenger'" might
           output:

               Mail Avenger <myname+tmp+zjkifk8kuvsy7rubu7vqadmwnn@host>

           Note that if the MACUTIL_SENDER environment variable has been set, this will be used
           as a default value for the --sender option if you invoke macutil --from and don't
           specify a --sender.

       --fromexp phrase
           In conjunction with the --from option, this option includes an expiration time for the
           address in a comment.  For example, supplying a phrase of "address expires" would
           result in output like this:

               Mail Avenger (address expires 07 Dec 2004)
                   <myname+tmp+zjkifk8kuvsy7rubu7vqadmwnn@host>

       --check (-c)
           Checks a code, as described above.  Exits 0 on success; exits non-zero with a message
           to standard error if the code is invalid.

       --passfile=file (-p file)
           Specify the passphrase file to use.

           Note that if file contains multiple passphrases, one per line, --gen always uses the
           first passphrase in the file.  --check, however, will try all passphrases until one
           succeeds, and only output failure if they all fail.  In this way, you can change your
           passphrase, but keep accepting the old one for a time by leaving it as the second line
           of the file.

       --expire=date
           Specify the expiration date for the code.  date can be an absolute number of seconds
           since midnight, Jan 1, 1970, GMT.  Alternatively (and perhaps more usefully), it can
           be expressed relative to the current time, as:

           +numh
           +numD
           +numW

           to specify num hours, days, or weeks in the future.  The full range of suffixes
           allowed is s, m, h, D, W, M, and Y, which designate seconds, minutes, hours, days,
           weeks, months, and years, respectively.  The default expiration time is 21 days
           ("+21D").

       --aux=string
           Permutes the algorithm using string.  You must specify the same --aux argument when
           both generating and checking codes.  This allows you to re-use the same password for
           different sets of codes.  For example, you might require tokens generated with
           "macutil --gen --aux=list1" to be embedded in recipient addresses for one mailing
           list, and "macutil --gen --aux=list2" to be embedded in recipient addresses for
           another.  Someone who has an address that is valid for one list will still not be able
           to send to the other.

       --date=date
           Run as if the current time were date.  As with --expire, date can be an absolute
           number or can be relative to the current time.  Use - instead of + to specify a time
           in the past (e.g., -numh or -numD).

       --sendmail
           This option must be the last sendmac option.  It tells macutil to run sendmail with
           the remaining arguments you have specified, but to insert the options -f address at
           the beginning of the argument list, where address is generated as with the --sender
           option.  You must specify an address template, either through explicit use of the
           --sender option, or by setting the MACUTIL_SENDER environment variable.

           For example, if MACUTIL_SENDER is "myname+bounces+*", running "macutil --sendmail
           friend@domain.com" might run the command:

               sendmail -f \
                   myname+bounces+zjkifk8kuvsy7rubu7vqadmwnn \
                   friend@domain.com

           Note that if invoke the macutil program as "sendmac" (or as any other name you link it
           to beginning with the four letters "send"), it will automatically behave as though
           there were an extra first argument of --sendmail.  (In this case, you cannot specify
           any sendmac options, but you can still control sendmac's behavior through the
           environment variables listed below.)

ENVIRONMENT

       MACUTIL_EXPIRE
           Sets the expiration time if not explicitly overwritten by the --expire flag.  If
           MACUTIL_EXPIRE is not set, macutil uses a default value of "+21D" (21 days).

       MACUTIL_FROMEXP
           If this option is set to phrase, then the output of "sendmac --from" will always
           behave as though an extra --fromexp phrase argument had been supplied.

       MACUTIL_PASSFILE
           Specifies a passphrase file other than the default of $HOME/.avenger/.macpass.

       MACUTIL_SENDER
           Specifies a template sender address to use as a default value of --sender with the
           --sendmail and --from options.  See the descriptions of the --sendmail and --from
           options above for more information.

       MACUTIL_SENDMAIL
           Specifies the path to sendmail for the --sendmail option.  The default is just
           sendmail.

FILES

       $HOME/.avenger/.macpass

SEE ALSO

       avenger(1)

       The Mail Avenger home page: <http://www.mailavenger.org/>.

BUGS

       macutil is designed to provide casual security against people trying to guess a valid
       temporary email address.  Don't use it where stronger authentication is required.  In
       particular, for any given passphrase, a random code will be valid (at least on some date)
       with probability 1 in 2^64.  While these are tough odds to beat, cryptographers generally
       prefer a margin of safety closer to 1 in 2^128 for high-security applications (though that
       would require longer codes).

       Someone who sees a valid code can mount an off-line dictionary attack against your
       passphrase.  In other words, while it is hard recover your passphrase outright, given a
       valid code, it is is easy to verify whether a particular guess of your passphrase is
       correct.  By guessing every word in the dictionary, an attacker can recover weak
       passphrases.

       Technically, the cryptographic operation performed on the keys is encryption, not a
       message authentication code (or MAC).  Hence, one could argue the utility is misnamed.

AUTHOR

       David Mazieres