Author: dbkr
Date: 2006-07-24 19:50:45 +0000 (Mon, 24 Jul 2006)
New Revision: 9741
Modified:
trunk/apps/Freemail/docs/spec/spec.tex
Log:
Formatting and spelling corrections on spec doc.
Modified: trunk/apps/Freemail/docs/spec/spec.tex
===================================================================
--- trunk/apps/Freemail/docs/spec/spec.tex 2006-07-23 21:18:05 UTC (rev
9740)
+++ trunk/apps/Freemail/docs/spec/spec.tex 2006-07-24 19:50:45 UTC (rev
9741)
@@ -4,11 +4,11 @@
\date{July 2006}
\maketitle
-This is a working draft of the Freemail spcification. All parts of this
document are subject to change.
+This is a working draft of the Freemail specification. All parts of this
document are subject to change.
\section{Introduction}
\subsection{What is Freemail}
-Freemail is an email-like messaging system that transports all messages over
Freenet 0.7 in order to achieve anonymity and cencorship-resillience. Its
protocol is designed to be as resistant as possible to attacks such as message
floods and denial of service. Unlike traditional email, it makes it extremely
difficult for others to doscover what you have been communicating, who you have
been communicating with, and even that you have been communicating at all.
+Freemail is an email-like messaging system that transports all messages over
Freenet 0.7 in order to achieve anonymity and censorship-resilience. Its
protocol is designed to be as resistant as possible to attacks such as message
floods and denial of service. Unlike traditional email, it makes it extremely
difficult for others to discover what you have been communicating, who you have
been communicating with, and even that you have been communicating at all.
Freemail uses IMAP and SMTP to interface with standard email clients, making
taking advantage of interfaces that people are already accustomed to.
@@ -18,9 +18,9 @@
All Freemail users have an Freemail address, which one may give out to others
in order to allow them to contact you. From this Freemail address, it is
possible to derive a Freenet SSK URI. This is the user's 'mailsite'.
-A Freemail address comprises an arbitrary text string, followed by an '@'
character. Following this is the mailsite address encoded in base 32 - that is,
a valid Freenet uri that points to the mailsite. The URI must be base 32
encoded in order to make the address case insensitive to maintain compatability
with traditional email clients. The string '.freenet' is appended to the whole
address. An example Freemail address follows:
+A Freemail address comprises an arbitrary text string, followed by an '@'
character. Following this is the mailsite address encoded in base 32 - that is,
a valid Freenet uri that points to the mailsite. The URI must be base 32
encoded in order to make the address case insensitive to maintain compatibility
with traditional email clients. The string '.freenet' is appended to the whole
address. An example Freemail address follows:
-bob at
JRHXORDZIQZFIVDJ\-GBDHEVLDO43TATSCGJST\-C3CXJ5NHSTL6NM2HQ\-NDONNXG632COJFD\-ALBVKJ2HS5LLNQ3E\-OLKQOFKUKNCMG5F\-GYODBJBYVSYLPOVZ\-WMV3GOBRHGOLVMJ\-ZUSY3DOY2CY\-QKRIFBECQKF.freemail
+bob at
JRHXORDZIQZFIVDJ\-GBDHEVLDO43TATSCGJST\-C3CXJ5NHSTL6NM2HQ\-NDONNXG632COJFD\-ALBVKJ2HS5LLNQ3E\-OLKQOFKUKNCMG5F\-GYODBJBY\-VSYLPOVZ\-WMV3GOBRHGOLVMJ\-ZUSY3DOY2CY\-QKRIFBECQKF.freemail
The base 32 encoded mailsite in this case is:
LOwDyD2TTi0FrUcw70N\-B2e1lWOZyM~k4x4n\-knooBrJ0,5Rtyu\-kl6G-PqUE4L7\-Jl8aHqYaous\-fWfpbs9ubsI\-ccv4,AQABAAE
@@ -34,7 +34,7 @@
\begin{itemize}
\item rtskey - This is an arbitrary string of alphanumeric characters which is
used to derive a KSK that can be used to send data to the owner of the mailsite
in order to establish a communication channel.
\item asymkey.modulus - The modulus of the owner's RSA encryption key, as an
integer in base 10.
-\item asymkey.pubexponent - The public exponent of the owner's RSA encruption
key, as an integer in base 10.
+\item asymkey.pubexponent - The public exponent of the owner's RSA encryption
key, as an integer in base 10.
\end{itemize}
\subsection{RTS Messages}
@@ -42,11 +42,11 @@
\begin{itemize}
\item commssk - The public SSK URI to which messages will be inserted.
-\item ackssk - A fresh SSK private (insert) key that Bob will insert to in
order to acknowledge his reciept of each message.
+\item ackssk - A fresh SSK private (insert) key that Bob will insert to in
order to acknowledge his receipt of each message.
\item messagetype - This should be 'rts', to indicate that this message is an
RTS.
-\item to - The Freenet URI that appears encoded in Bob's Freemail address.
This is necessary in order to prevent surreptitious forwarding to support the
enryption explained later.
+\item to - The Freenet URI that appears encoded in Bob's Freemail address.
This is necessary in order to prevent surreptitious forwarding to support the
encryption explained later.
\item mailsite - Alice's mailsite URI
-\item ctsksk - A randomly generated KSK that Bob should insert to once he has
recieved Alice's RTS message in order to acknoweldge that he is ready to
recieve messages. This should be randomly generated and un-guessable so that
only Bob knows which key to insert to.
+\item ctsksk - A randomly generated KSK that Bob should insert to once he has
received Alice's RTS message in order to acknowledge that he is ready to
receive messages. This should be randomly generated and un-guessable so that
only Bob knows which key to insert to.
\end{itemize}
Following the last data item, there are two carriage-return-line-feeds,
followed by Alice's signature. This is the SHA-256 hash of the message RSA
encrypted with Alice's private key, included as raw bytes. The resulting
message is then RSA encrypted with Bob's public key. If the resulting message
is longer than a single RSA block, the message is encoded in chunks equal to
the maximum block size and the ciphertext blocks are concatenated to form the
final message.
@@ -55,32 +55,32 @@
The 'to' field is included to prevent surreptitious forwarding. That is, to
prevent Bob from decrypting the message, leaving Alice's signature intact and
encrypting it to someone else (say, Charlie), who would then be lead in to
believing that Alice wished to communicate with him, which is fact not the case.
-This RTS message is then inserted to Freenet. The URI which it inserted to is
derived from the 'rtskey' value in Bob's mailsite. The string, 'KSK@' is
prepended a hyphen, the current date in the standard date format (see section
\ref{standard_date}) is appended, followed by another hypen and a slot number.
The slot number should be set to the lowest integer starting from 1, that does
not cause a collision.
+This RTS message is then inserted to Freenet. The URI which it inserted to is
derived from the 'rtskey' value in Bob's mailsite. The string, 'KSK@' is
prepended a hyphen, the current date in the standard date format (see section
\ref{standard_date}) is appended, followed by another hyphen and a slot number.
The slot number should be set to the lowest integer starting from 1, that does
not cause a collision.
-Alice then regularly polls the KSK she put as the value of 'ctsssk' until she
retrives a CTS message (see next section).
+Alice then regularly polls the KSK she put as the value of 'ctsssk' until she
retrieves a CTS message (see next section).
\subsection{CTS Messages}
-When Bob recieves an RTS message from Alice, he decrypts the message using his
RSA private key. He then retrives the mailsite advertised in the RTS message.
Having done this, he reads the signature on the end and decrypts the signature
with the public key he just retrieved from the mailsite. He then calculates a
SHA-256 checksum of the message and checks that his checksum is identical to
the one he has decrypted. If it is not, he must discard the message. This
ensures that the message is really from Alice. He must then read the 'to' field
and ensure that its value is identical to his mailsite URI. If it is not, he
must discard the message. This ensures that he is the intended recipient of the
message.
+When Bob receives an RTS message from Alice, he decrypts the message using his
RSA private key. He then retrieves the mailsite advertised in the RTS message.
Having done this, he reads the signature on the end and decrypts the signature
with the public key he just retrieved from the mailsite. He then calculates a
SHA-256 checksum of the message and checks that his checksum is identical to
the one he has decrypted. If it is not, he must discard the message. This
ensures that the message is really from Alice. He must then read the 'to' field
and ensure that its value is identical to his mailsite URI. If it is not, he
must discard the message. This ensures that he is the intended recipient of the
message.
-Bob then records the value of the 'commssk' key so that he can poll this SSK
for messages periodicaly.
+Bob then records the value of the 'commssk' key so that he can poll this SSK
for messages periodically.
Before doing so, Bob inserts some data to the value of the 'ctsksk' key in the
RTS message. The data he inserts is irrelevant - the presence of the key is
sufficient to prove to Alice that he has received the message. This completes
Bob's part of the channel setup procedure.
This message contains no valuable information and so does not need to be
encrypted. It also does not need to be signed since only Alice and Bob know the
KSK to which it must be inserted, so Alice knows that Bob must have inserted
the message. The KSK that Bob inserts this message to tells Alice what RTS it
relates to if there is any ambiguity.
-Alice should check periodically for the insertion of this CTS message. If it
does not arrive, Alice should re-send the RTS message with a different
'ctsssk', in order that she can be certain which RRS message any given CTS
message corresponds to. All other field should be the same. The client may try
several times before declaring the message undeliverable.
+Alice should check periodically for the insertion of this CTS message. If it
does not arrive, Alice should re-send the RTS message with a different
'ctsssk', in order that she can be certain which RTS message any given CTS
message corresponds to. All other field should be the same. The client may try
several times before declaring the message undeliverable.
\section{Message Exchange}
\subsection{The Messages}
-Once Bob has inserted this CTS message, he begins polling for messages on keys
derived from the value of the 'commssk' key which he obtained from the RTS
message. These keys are the value of 'comssk' with the string 'message-' and a
natural number appended, where the number is the lowest number that does not
form a key on which Bob has already received a message (the 'lowest free
slot'). For example:
+Once Bob has inserted this CTS message, he begins polling for messages on keys
derived from the value of the 'commssk' key which he obtained from the RTS
message. These keys are the value of 'commssk' with the string 'message-' and a
natural number appended, where the number is the lowest number that does not
form a key on which Bob has already received a message (the 'lowest free
slot'). For example:
SSK at
9GXtGxN4CEJD~8a30\-7V6yzyhl8Gx5UYb\-WVDTEyUXH6o,gDWfr2CqVmDAeJ\-urKF2iieM5AkjXs\-tOl2V5jyuTHeo4,AQABAAE/message-1
-Once Bob has successfully retrived this key, he begins to periodically request
the key:
+Once Bob has successfully retrieved this key, he begins to periodically
request the key:
SSK at
9GXtGxN4CEJD~8a30\-7V6yzyhl8Gx5UYbW\-VDTEyUXH6o,gDWfr2CqVmDAeJ\-urKF2iieM5AkjXs\-tOl2V5jyuTHeo4,AQABAAE/message-2
-It is recommended that clients poll several messages ahead rather than just
the immediately next message, since simulations suggest that it is possible for
single keys not to be retrivable in this kind of circumstance. So for example,
once Bob has sent his CTS messages, he should start polling for the keys:
+It is recommended that clients poll several messages ahead rather than just
the immediately next message, since simulations suggest that it is possible for
single keys not to be retrievable in this kind of circumstance. So for example,
once Bob has sent his CTS messages, he should start polling for the keys:
number that does not form a key on which Bob has already received a message
(the 'lowest free slot'). For example: \\
\\
@@ -93,10 +93,10 @@
Alice can insert a message to the lowest numbered key of this pattern that
does not cause a collision whenever she chooses. These comprise a number of
properties (in the same way as a props file) followed by a double
carriage-return-line-feed. Following this is the standard MIME mail messages.
No signing or encryption is used here, since at this stage it is achieved
inside Freenet by virtue of only Alice and Bob knowing the SSK upon which they
communicate.
-The only mandatory property is 'id' which may be any integer, but must
uniquely identify the message from any other past or future message transported
using the same 'commssk'. Bob must check this value and ensure that he has not
already recieved this message id. If he has, he discards the message, but still
ackowledges his reciept of it. All clients must ignore any unknown keys and
begin reading the message only at the double line break in order that extra
properties can be added in the future.
+The only mandatory property is 'id' which may be any integer, but must
uniquely identify the message from any other past or future message transported
using the same 'commssk'. Bob must check this value and ensure that he has not
already received this message id. If he has, he discards the message, but still
acknowledges his receipt of it. All clients must ignore any unknown keys and
begin reading the message only at the double line break in order that extra
properties can be added in the future.
\subsection{Message Acknowledgements}
-When Bob recieves a message on the 'commssk', he reads it and passes it onto
the user. He then inserts some data to the key 'ackssk' (which he obtains from
the original RTS message) with 'ack-' and the value of 'id' from the message in
question. For example, if Bob has just fetched a message from key: \\
+When Bob receives a message on the 'commssk', he reads it and passes it onto
the user. He then inserts some data to the key 'ackssk' (which he obtains from
the original RTS message) with 'ack-' and the value of 'id' from the message in
question. For example, if Bob has just fetched a message from key: \\
\\
SSK at
9GXtGxN4CEJD~8a\-307V6yzyhl8Gx5U\-YbWVDTEyUXH6o,gDWfr2CqVm\-DAeJurKF2iieM\-5AkjXstOl2V5j\-yuTHeo4,AQABAAE/message-1
\\
\\
@@ -118,13 +118,13 @@
\\
SSK at
AJoZbUvGkXlAJwI\-jdbu9BLPhpIXBu6\-w6nGwKYBnMfNLi,ACEgE1uUIzJdC\-Xcsz1yjgW45u\-Az-KuMrXBFYG\-U8maqc/ack-657488664753
\\
\\
-The data that Bob publishes to this key is irrelevant - its mere existance in
the network is sufficient to assert Bob's reciept of the message. If Alice has,
for whatever reason, not received a CTS message from Bob, her receipt of a
message ack should additionally be treated as receipt of a CTS message.
+The data that Bob publishes to this key is irrelevant - its mere existence in
the network is sufficient to assert Bob's receipt of the message. If Alice has,
for whatever reason, not received a CTS message from Bob, her receipt of a
message ack should additionally be treated as receipt of a CTS message.
\appendix
\section{Props Files}
\label{PropsFile}
-A props file is a sequence of keys and values. Keys and values are separated
by a single equals sign ('=') and lines are separated by a carrriage return and
line feed ($\backslash$r$\backslash$n), with the exception that if the
propsfile will only be read locally, it is permissable to use the line
separator native to the local machine. For example, for props files that are
never transmitted over the network, it is permissable to use just a line feed
($\backslash$n) to separate lines. It is recommended for simplicity, though not
required, that the keys be lowercase and contain only alphanumeric characters.
The keys must not contain the equals sign, as there is no mechanism for
escaping equals signs. The value may contain equals signs and therefore parsers
of this format must treat and equals signs after the first on any line as part
of the value text.
+A props file is a sequence of keys and values. Keys and values are separated
by a single equals sign ('=') and lines are separated by a carriage return and
line feed ($\backslash$r$\backslash$n), with the exception that if the
propsfile will only be read locally, it is permissable to use the line
separator native to the local machine. For example, for props files that are
never transmitted over the network, it is permissable to use just a line feed
($\backslash$n) to separate lines. It is recommended for simplicity, though not
required, that the keys be lowercase and contain only alphanumeric characters.
The keys must not contain the equals sign, as there is no mechanism for
escaping equals signs. The value may contain equals signs and therefore parsers
of this format must treat and equals signs after the first on any line as part
of the value text.
An example of a propsfile is below: \\
\\
@@ -137,6 +137,6 @@
\section{Standard Date Format}
\label{standard_date}
-A date in the standard format is the four digit year, two digit month and two
digit day of the month. That is, "yyyyMMdd" in Java's SimpleDateFormat class
notation. This is used to encode the day upon which and Freenet KSK key is
inserted. For the purposes of considering when a key is inserted, this should
be done accoring to Universal Standard Time, and not any local timezone or
daylight saving time.
+A date in the standard format is the four digit year, two digit month and two
digit day of the month. That is, "yyyyMMdd" in Java's SimpleDateFormat class
notation. This is used to encode the day upon which and Freenet KSK key is
inserted. For the purposes of considering when a key is inserted, this should
be done according to Universal Standard Time, and not any local timezone or
daylight saving time.
\end{document}
