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-1 and MD5. For more information, see: http://en.wikipedia.org/wiki/HMAC http://www.faqs.org/rfcs/rfc2104.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. 2. If the new HMAC does not match, a new HMAC is generated against the sender's fully qualified domain. If there is still no match, one level of qualification is stripped (eg, 'DOMAIN.DOM' -> 'DOM') and a new HMAC is generated and compared. The process repeats until a match is found or no more domain parts remain. Keyword Addresses: ------------------ The format for a 'keyword' address is: USERNAME-keyword-KEYWORD.KEYWORDMAC@DOMAIN.DOM (For example, jason-keyword-promos.8w06e8@mastaler.com) KEYWORD can be any string. KEYWORDMAC is an HMAC of KEYWORD. 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-TIMESTAMP.PID.CONFIRMMAC@DOMAIN.DOM (For example, jason-confirm-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'. Once accepted, an 'X-TMDA-Confirm-Done:' header containing TIMESTAMP, PID, and CONFIRMMAC (based on string 'done' rather than 'accept') is added to the message, and then it is reinjected to the original recipient. Upon reception, TMDA verifies the HMAC by recalculation before delivering the message. 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.