Cryptography in TMDA
--------------------

For crypto-cookie generation and verification, TMDA uses HMAC, which
is a mechanism for message authentication using cryptographic hash
functions such as SHA and MD5.

For all the relevant papers and RFCs see:
    <URL:http://www-cse.ucsd.edu/users/mihir/papers/hmac.html>


Dated Addresses:
----------------

The format for a 'dated' address is:

    USERNAME-dated-DATE.DATEMAC@DOMAIN.DOM

    (For example, jason-dated-988298746.9d619c@mastaler.com)

    DATE is seconds since the epoch in UTC, expressed as an integer.
  
    DATEMAC is an HMAC of DATE.

Incoming 'dated' messages are accepted if:

    1.  DATE >= the current time (i.e, not yet expired) 

        *AND* 

    2.  DATEMAC is verified by matching it with a new HMAC generated
        against DATE.

    DATEMAC verification prevents any tampering with DATE.

Sender Addresses:
-----------------

The format for a 'sender' address is:
    
    USERNAME-sender-SENDERMAC@DOMAIN.DOM

    (For example, jason-sender-8c54ac@mastaler.com)

    SENDERMAC is an HMAC of the sender's e-mail address.

Incoming 'sender' messages are accepted if:

    1.  SENDERMAC is verified by matching it with a new HMAC generated
        against the sender's e-mail address.

Keyword Addresses:
------------------

The format for a 'keyword' address is:
    
    USERNAME-KEYWORD.KEYWORDMAC@DOMAIN.DOM

    (For example, jason-promos.8d06eu@mastaler.com

    KEYWORD can be any string.

    KEYWORDMAC is an HMAC of KEYWORD.

Unlike other tagged addresses, 'keyword' addresses are not keyed with
identifying strings ('-dated-', '-sender-', etc.).

Incoming 'keyword' messages are accepted if:

    1.  KEYWORDMAC is verified by matching it with a new HMAC
	generated against the KEYWORD.

Confirmation Requests:
----------------------

The format for a confirmation request address is:

    USERNAME-confirm-accept.TIMESTAMP.PID.CONFIRMMAC@DOMAIN.DOM

    (For example, jason-confirm-accept.995399954.1345.c08f32@mastaler.com)

    TIMESTAMP the arrival time of the message in seconds since the
    epoch.

    PID is the process-id of the current Python process.

    CONFIRMMAC is an HMAC as a function of TIMESTAMP, PID, and the
    string 'accept'.

Confirmation request acknowledgments are accepted if:

    1.  CONFIRMMAC is verified by matching it with a new HMAC
	generated against TIMESTAMP, PID, and 'accept'.


HMAC Advantages:
----------------

Using HMACs offers several advantages over the former use of block
cipher encryption without any loss of security:

* The amkCrypto package is no longer necessary as TMDA includes an
  HMAC implementation that uses Python's `sha' module for hashing.
  Thus, only the core Python distribution is needed to run TMDA.
  amkCrypto/OpenSSL compilation/installation difficulties proved to be
  the biggest stumbling block for new users of earlier TMDA releases.

* The default "cookies" are shorter.  (6 hex characters as compared to
  16 for 'dated', and 6 hex characters as compared to 40 for 'sender')

* It is the right construction to be using from a cryptographic
  perspective.  (MACs were designed for exactly these type of
  message authentication tasks)


TMDA Security:
--------------

With HMACs, the length of the key determines how hard it is to "break"
the system; that is, find the key and be able to forge arbitrary
messages (create arbitrary email addresses, in this context).  With
this in mind, TMDA uses long (160-bit) random private keys.

One way to try to sneak messages past TMDA would be to simply pick a
random string as the HMAC and hope that it verified correctly.  The
length of the HMAC determines the likelihood that a random message is
a forgery.  If you use n bits in your HMAC, the chance of this is 1 in
2**n.  By default, TMDA uses 24-bit HMACs (3 bytes, 6 hex characters).
Here are some statistics for HMACs of various sizes:

HMAC_BYTES  CHARS  BITS  CHANCE OF FORGERY       EXAMPLE
----------  -----  ----	 -----------------	 -------
1	    2      8	 1 in 256		 e9
2	    4      16    1 in 65,536		 f9c4
3	    6      24    1 in 16,777,216	 3fd2f2
4	    8      32    1 in 4,294,967,296	 596b0ba3
5	    10     40    1 in 1,099,511,627,776	 490e78c8d9
[...]

You can alter the length of your HMACs (through HMAC_BYTES) if you are
not comfortable with the default.  However, the default should provide
sufficient protection when you consider that to test a forged HMAC,
the attacker must actually send you an e-mail message and wait for the
result.  Longer HMACs also mean longer e-mail addresses to work with.

