Freemail specification

Freemail channels are designed so as to maximum privacy, anonymity, and reliability. Use of the Freenet architecture allows cultivation of anonymous identities with widespread reputations. The locations of mail messages within Freenet are constructed and transmitted in such a way that only the parties involved are aware of the source, destination, and even transmission of the messages. Eavesdropping is prevented by the use of strong encryption (Diffie- Hellman negotiated symmetric keys). Forgery is prevented by the use of Freenet's secure subspace key concept and cryptographic signatures. Freemail relies on the robustness of Freenet's secure key subspaces to prevent denial-of-service attacks on established channels.

The reference implementation of Freemail is written in Java. Encryption functionality is provided by the Java Cryptography Engine. XML parsing and serialization is provided by the Apache Xerces library (by way of IBM's xml4j).

Currently, Freemail requires Sun's Java 2 v1.4 Runtime Environment. The implementation has been tested on Linux, Solaris, and Windows.

How to Read This Document

This document provides a top-level specification of the Freemail protocol, as implemented by the reference program. Though this document fully specifies the behavior of Freemail, it may not contain all the information necessary to produce a compatible implementation.

Freemail Protocol Overview

Freemail provides channels, which convey information bidirectionally between two parties. The Freemail protocol is designed to allow channels to be securely formed between parties with no existing method of communication, thereby preserving the anonymity of both parties.

Channel Initiation

The channel initiation protocol specifies how one party (the "requester") can establish a channel with another party (the "requestee") who is known to the requester. It is unnecessary for the requestee to have any previous knowledge of the requester. All messages transmitted during channel initiation are secured with Triple-DES keys as specified below, preventing eavesdropping on the channel parameters. These parameters are required before an attacker may even detect the transmission of mail messages. The following phases define the creation and secure, reliable exchange of channel parameters.

Identity creation phase

Initially, a requestee must create a document called an "identity" establishing how requesters may contact him. This document (or, preferably, an address locating it) should be distributed in public communications, allowing other users to confidently associate those communications with the Freemail identity. The following steps describe the creation of an identity.

The requestee uses the Freenet Client Protocol (FCP) to request an SSK keypair from his Freenet node. The public SSK key is the requestee's Freemail address, and uniquely identifies him.

The requestee specifies an alias, analagous to the name header in an email, which provides a user-friendly moniker for other Freemail user's to know him by. This name may be changed at any time and is not used within Freemail itself.

The requestee generates parameters (a prime p and base g) for the Diffie-Hellman (DH) protocol. These are the negotiation DH parameters.

The requestee generates a DH keypair with the DH negotiation parameters. This keypair is the requestee's negotiation DH keypair.

The requestee's identity document is created containing:
- The requestee's alias.
- The requestee's SSK public key.
- The negotiation DH parameters.
- The requestee's negotiation DH public key.
The format of this document is specified
below.

Channel request phase

Once the requestee has established a reputation associated with his Freemail identity, users may wish to contact him. Though dissemination and retrieval of the identity is not specified by Freemail, publishing it into Freenet is a sensible practice. Once a requester has obtained the requestee's identity, she can use it to contact said requestee. The following steps describe the process of contacting the requestee described above.

The requester somehow learns of the requestee's identity and retrieves it.
The requester generates an identity (as above) if she has not done so before. This includes the requester's alias and SSK public key.
The requester uses the negotiation DH parameters created by the requestee to generate the requester's negotiation DH keypair.
The requester generates the Triple-DES negotiation symmetric key by DH key agreement with the requestee's negotiation DH public key and her own negotiation DH private key. Along with the negotiation symmetric key the requester computes algorithm parameters compatible with the negotiation symmetric key; these are the negotiation symmetric parameters.
The requester generates a random, unguessable string, for use as a channel name (see Mail). This is the requester-to-requestee channel name.
The requester generates a Blowfish secret key unassociated with any others, and any necessary parameters. These are the requester-to-requestee symmetric key and requester-to-requestee symmetric parameters.
The requester generates a random, unguessable key within the requestee's SSK subspace specifying a location where the requestee should publish a receipt of the channel request if it is accepted. This the channel's receipt address.
The requester packages a channel request message containing:
- The requester's negotiation DH public key.
- The negotiation symmetric parameters.
- The following, encrypted by the negotiation symmetric key in association with the negotiation symmetric parameters:
  - The requester's alias.
  - The requester's SSK public key.
  - The requester-to-requestee channel name.
  - The requester-to-requestee symmetric key.
  - The requester-to-requestee symmetric parameters.
  - The receipt address.
The format of this document is specified below.
The requester transmits the request by one of the request transmission protocols (see Request Transport.
The requester stores a record of the unopened channel.

Channel acceptance phase

The requestee retrieves the requester's channel proposal according to the request transmission prococol used by the requester.
The requestee extracts the requester's negotiation public DH key and the negotiation symmetric parameters. The requestee also computes the negotiation symmetric key by DH key agreement between the requester's negotiation public DH key and the requestee's negotiation private DH key. This is the same key used by the requester, courtesy of the DH protocol. Only these two parties know the key.
The requestee decrypts the remainder of the request using the negotiation symmetric key and parameters.
As did the requester, the requestee generates a secret key unassociated with any others, and matching parameters. These are the requestee-to-requester symmetric key and requestee-to-requester symmetric parameters.
The requestee generates a random, unguessable string, for use as a channel name (see Mail Protocol). This is the requestee-to-requester channel name.
The requestee publishes a receipt at the location specified by the requester. The receipt contains the following, encrypted by the negotiation symmetric key in association with the negotiation symmetric parameters:
- The requestee-to-requester channel name.
- The requestee-to-requester symmetric key.
- The requestee-to-requester symmetric parameters.
The format of this document is specified below.
The requestee stores a record of the channel. He now considers both sides of the channel open, and he may send and receive mail. The channel inbound to him is specified by the requester's public SSK key and the requester-to-requestee channel name, and encrypted by the requester-to-requestee symmetric key in association with the requester-to-requestee symmetric parameters. The channel outbound to the requester is specified by the requestee's public SSK key and the requestee-to-requester channel name, and encrypted by the requestee-to-requester symmetric key in association with the requestee-to-requester symmetric parameters.

Channel confirmation phase

The requester periodically checks the known receipt location.
After the requestee publishes the receipt, the requester retrieves it.
The requester decrypts the receipt using the negotiation symmetric key and negotiation symmetric parameters.
The requester stores a record of the channel. Shee now considers both sides of the channel open, and she may send and receive mail. The channel inbound to her is specified by the requestee's public SSK key and the requestee-to-requester channel name, and encrypted by the requestee-to-requester symmetric key in association with the requestee-to-requester symmetric parameters. The channel outbound to the requestee is specified by the requester's public SSK key and the requester-to-requestee channel name, and encrypted by the requester-to-requestee symmetric key in association with the requester-to-requestee symmetric parameters.

Request Transport

The anonymous-introduction capability of Freemail presents difficulties in that an attacker can pretend to be many legitimate users and flood a requestee with many requests. Freemail provides a variety of request transport protocols to work around this fundamental limitation, and limit the damage of such attacks when they occur.

1) Fixed-Window Publication

This method establishes a public address space within Freenet where new senders may place proposals of new channels for a recipient. The address space is implied by a user's address (i.e., public SSK key), and takes the form KSK@freemail/requests/<requesteePublicSSKKey>/<slot>. To publish a request into this "slotbox", a requester attempts to retrieve request documents, starting from slot=1. The requester then publishes her request in the first empty slot.

This method has the usual disadvantages associated with slot-based KSK boxes (also used in Frost in FMB, for instance). In particular, this method is susceptible to message loss (where a requester publishes a request in a slot that was once filled but whose request subsequently disappeared from Freenet), and denial-of-service attacks (where an attacker fills the slotbox with garbage requests, forcing both the requestee and requesters to search through many slots unnecessarily).

This channel is fairly reliable under normal circumstances (depending on Freenet conditions), and highly unreliable under attack. However, the reliability degrades over time as early requests disappear from the network.

2) Dynamic-Window Publication

This method extends the fixed-window method by providing for a moving request publication address. Specifically, a new KSK subspace is generated for proposal messages at a regular interval or as needed. The location of the subspace is published in an SSK key which is updated whenever the proposal window changes. Currently this is achieved with a Freenet DBR key, which essentially changes content with a defined frequency (typically one day).

This method makes denial of service attacks more difficult, as an attacker must constantly follow the moving proposal window in order to flood it. However, the extra layer of redirection decreases the reliability of this method. Additionally, a persistent attacker may still hinder establishment of new channels.

Compared to the fixed-window method, this method is less reliable under normal circumstances, much more reliable under sustained attacks, and less reliable under unsustained attack. Unlike the fixed-window method, however, this method does not suffer from a decay in reliability over time.

Sending

The sender generates a message document containing helpful message headers (timestamp, digital signature, etc.). Note that these are not the email headers that may be in the message text as generated by a mail user agent; they are Freemail-specific. A randomly generated unique id, the public SSK keys of the sender and recipient must be included in these headers; any others are optional and purely informational.
The sender encrypts the message with the outbound symmetric key.
The sender publishes the message in the next open slot. The slot address prefix is given by SSK@<senderPublicSSKKey>/<outboundChannelName>/. Note that no search is required to find the next slot; since only the sender can write to the outbound channel, the next available slot is simply the slot after the one most recently filled.

Receiving

The recipient checks for new messages by searching the slotbox, starting from the last slot which contained a message.
The recipient receives the new message and decrypts it.
The recipient unpacks the headers and the content.

Message and Storage Formats

All message and mailbox information storage data are enclosed in XML. The following DTDs specify document types used in Freemail (note that Freemail currently does its own validation and does not use these DTDs internally). Documents that include a "version" field are intended for wire transmission (possibly encrypted). Freemail implementations are explicitly disallowed from processing a document whose version is more recent than that included in said implementation. All versioned documents are currently at version "0.1".

NOTE: Some portions of these DTDs are out of date pending further revision.

Mailstore Information

The mailstore file contains the information necessary for sending and receiving Freemail messages. This is typically a disk file. The mailstore should never be distributed, as it contains private and secret keys in cleartext.


<!DOCTYPE mailstore [
     <!ELEMENT mailstore (version,alias,publicSSKKey,privateSSKKey,
        privateDHKey,publicDHKey,dhParamSpecG,dhParamSpecP,cryptoParams,
        lastIndexProposal,inbox*,outbox*)>
     <!ELEMENT version (#PCDATA)>
     <!ELEMENT alias (#PCDATA)>
     <!ELEMENT publicSSKKey (#PCDATA)>
     <!ELEMENT privateSSKKey (#PCDATA)>
     <!ELEMENT privateDHKey (#PCDATA)>
     <!ELEMENT publicDHKey (#PCDATA)>
     <!ELEMENT dhParamSpecG (#PCDATA)>
     <!ELEMENT dhParamSpecP (#PCDATA)>
     <!ELEMENT cryptoParams (#PCDATA)>
     <!ELEMENT lastIndexProposal (#PCDATA)>
     <!ELEMENT inbox (alias,senderPublicSSKKey,channelName,secretKey,
        cryptoParams,lastMessageIndex)>
     <!ELEMENT outbox (alias,channelName,recipientPublicSSKKey,secretKey,
        cryptoParams,lastMessageIndex)>
     <!ELEMENT senderPublicSSKKey (#PCDATA)>
     <!ELEMENT recipientPublicSSKKey (#PCDATA)>
     <!ELEMENT channelName (#PCDATA)>
     <!ELEMENT secretKey (#PCDATA)>
     <!ELEMENT lastMessageIndex (#PCDATA)>
     ]>

User Identity

The user identity contains information necessary to contact a recipient via Freemail. The current version of this document only supports the static dropbox contact protocol.


<!DOCTYPE identity [
     <!ELEMENT identity (version,alias,recipientPublicSSKKey,
        dhParamSpecG,dhParamSpecP,recipientPublicDHKey,cryptoParams)>
     <!ELEMENT version (#PCDATA)>
     <!ELEMENT alias (#PCDATA)>
     <!ELEMENT recipientPublicSSKKey (#PCDATA)>
     <!ELEMENT dhParamSpecG (#PCDATA)>
     <!ELEMENT dhParamSpecP (#PCDATA)>
     <!ELEMENT recipientPublicDHKey (#PCDATA)>
     <!ELEMENT cryptoParams (#PCDATA)>
     ]>

Channel Request

At the top level, a channel request is composed of three parts: the requester's Diffie-Hellman public key, the negotiation symmetric parameters (for 3DES), and the request data. The DH key part is a Base64 encoding of the byte data of the serialized key. ("Base64" is an encoding scheme that contains 6 bits of data per character; Freemail uses a custom Base64 encoding that is not compatible with that used by Freenet.) The negotiation symmetric parameters are also Base64-encoded. The request document (specified by the following DTD) is encrypted with the negotiation symmetric key and encoded as a Base64 string as well. The three Base64-encoded strings are delimited by linefeeds ('\n').


<!DOCTYPE request [
     <!ELEMENT request (version,requesterAlias,ee2erChannelName,
         ee2erSecretKey,ee2erCryptoParams,receiptAddress,negotiationSecretKey?,
         negotiationCryptoParams?)>
     <!ELEMENT version (#PCDATA)>
     <!ELEMENT requesterAlias (#PCDATA)>
     <!ELEMENT ee2erChannelName (#PCDATA)>
     <!ELEMENT ee2erSecretKey (#PCDATA)>
     <!ELEMENT ee2erCryptoParams (#PCDATA)>
     <!ELEMENT receiptAddress (#PCDATA)>
     <!ELEMENT negotiationSecretKey (#PCDATA)>
     <!ELEMENT negotiationCryptoParams (#PCDATA)>
     ]>

The elements are defined as follows:

version: The document version.
requesterAlias: The requester's alias.
ee2erChannelName: The requestee-to-requester channel name.
ee2erSecretKey: The requestee-to-requester symmetric key.
ee2erCryptoParams: The requestee-to-requester symmetric parameters
receiptAddress: The channel's receipt address.
negotiationSecretKey: The negotiation symmetric key (only when serialized in a mailstore).
negotiationCryptoParams: The negotiation symmetric parameters (only when serialized in a mailstore).

Request Receipt

The request receipt provides acknowledgment of a channel request's acceptance, and provides channel parameters not included in the request. The information is split in this manner so that each user can specify the maximum key strength he is capable of using, and to mediate damage caused by a compromised random number generator on one side (however unlikely).

Mail Message

Freemail messages are transported according to the following DTD. The content section is Base64-encoded to prevent XML-escaping difficulties. The serialized XML document is then encrypted with the channel's outbound secret key and inserted into Freenet as raw bytes.

Note that there may be more than one content section; these should be concatenated by the receiving client.


<!DOCTYPE message [
     <!ELEMENT message (version,content+,id,toAddress,fromAddress)>
     <!ELEMENT version (#PCDATA)>
     <!ELEMENT content (#PCDATA)>
     <!ELEMENT id (#PCDATA)>
     <!ELEMENT toAddress (#PCDATA)>
     <!ELEMENT fromAddress (#PCDATA)>
     ]>

Caveats

Freemail should be used as a secure communications platform only after a careful weighing of these considerations:

Freemail uses only tested implementations of well-known cryptographic algorithms. However, no cryptographic algorithm is proven, and the ability of other parties to decrypt your messages is always a possibility. Freemail currently uses the SunJCE implementation of these algorithms:
- Diffie-Hellman with 1024-bit keys for negotiating 3DES keys.
- Triple DES with 128-bit keys for channel negotiation messages.
- Blowfish with 128-bit keys for mail messages.
At present, these are considered "strong" algorithms with "strong" keysizes. However, they may not remain so indefinitely. Freenet may store your messages longer than you know, preserving your communications for future eavesdroppers with more powerful decryption tools. Also, be aware that the security of a channel's Blowfish keys is entirely compromised by the failure of its 3DES key (Blowfish is used for speed, while 3DES is used for compatibility with the JCE's Diffie-Hellman key agreement facilities).
Freenet may not be invulnerable to forgeries. Freemail relies on Freenet's SSK keys to prevent insertion of false messages. Should Freenet be vulnerable to such an attack, your channels may be vulnerable to forgery attacks (though not eavesdropping). You may wish to consider using separate document signing facilities provided through your mail user agent.
The identity of a Freemail user may be entirely fictitious. If a user unknown to you requests a channel with you, you should keep that anonymity in mind.

Glossary

Blind initiation - the process whereby a user sets up a channel with another user who has no previous knowledge of the first.
Identity - the collection of parameters necessary for a sender to contact a recipient. The identity is generated and published by a recipient.
Mailstore - the collection of parameters necessary for a particular user to send and receive mail. The mailstore is generated once per user and should be kept secret, as it contains confidential encryption keys and mailbox locations.
Channel name - an unguessable string that specifies a subspace in a sender's SSK space. Every channel contains two channel names: one for the outbound side and one for the inbound. The name is secret so as to prevent observers from observing the transport of messages.
Request - a message specifying a desire to coordinate a communication channel between the message's sender and recipient. The request contains information that the recipient may use to continue the channel initiation.
Recipient - a user who receives messages by Freemail; the target of a channel.
Sender - a user who sends messages by Freemail; the source of a channel.


Document revision:
$Author: athomasonx $
$Header: /cvsroot/freenetmail/freenetmail/docs/specification.html,v 1.3 2002/06/09 23:39:19 athomasonx Exp $
$Revision: 1.3 $
$Date: 2002/06/09 23:39:19 $
$Log: specification.html,v $
Revision 1.3  2002/06/09 23:39:19  athomasonx
Added XML DTDs.
Merged David Wei's dynamic dropbox spec.

Revision 1.2  2002/05/30 20:00:39  athomasonx
Added second stage protocol.
Added mail sending to usage example.

Revision 1.1  2002/05/29 01:48:56  athomasonx
Initial version.