\section{Composition of a Share}

Using an information dispersal algorithm, documents inserted into Free
Haven are split into \emph{n} pieces, any \emph{k} of which are
required to reconstruct the document.  A share contains one of these
\emph{n} pieces along with information about the specific share and
about the document.  Specifically, the share contains the public key
of the document, the share number, the share's buddy number, an
expiration date and time in Greenwich Mean Time (GMT), and a
signature.

An example of the share format is:

\begin{singlespace}
\begin{verbatim}
<share>
<PKdoc>cec41f889d75697304e89edbdddf243662d8c784</PKdoc>
<sharenum>1</sharenum>
<buddynum>0</buddynum>
<totalshares>100</totalshares>
<sufficientshares>60</sufficientshares>
<expiration>2000-06-11-22:25:24</expiration>
<data>Ascii-armored characters here</data>
<signature>cec41f889d75697304e89edbdddf243662d8c784</signature>
</share>
\end{verbatim}
\end{singlespace}

Shares have the following characteristics:
\begin{itemize}

\item Share information is completely enclosed inside the outermost
$<share>$ and $</share>$ tags.  Data before the $<share>$ and after
the $</share>$ is ignored.

\item The public key of the document is placed inside the $<PKdoc>$ tags.

\item Shares are numbered 0 through $n-1$.  The number of each share is
placed inside the \newline$<sharenum>$ tags.  This particular share represents
share 1 of the document.

\item Each share has a buddy share, which is one of the other shares of this
document.  The buddy number is placed inside the $<buddynum>$ tags.  In this
case, the buddy of this share is share number 0.  Because buddies are pairs,
then share 0's buddy would symmetrically be share 1.

\item Each share also includes the total number of shares that were created
for this document when this share was created, along with a value which
indicates how many shares are sufficient for reconstruction. These values
are there for convenience, and may well be superfluous.

\item The actual piece of the document as produced by the information
dispersal algorithm and represented by the share is placed between the
$<data>$ and $</data>$ tags.

\item The string inside of the $<expiration>$ tags represents the GMT time
when the share is free to be deleted.  This share, for example, will
expire at 10:25:24 pm on June 11, 2000.  Shares are not necessarily
deleted at their expiration time. Note that we zero-pad the datestamp --
this provides a fixed-width datestamp which may be convenient for reading
or automatic processing.

\item The information up to and including the $</data>$ tag is signed by
the cryptography module, and that value is placed inside the $<signature>$
tags. Specifically, this signature is done by taking all the tags,
removing whitespace between tags, and signing the resulting string.

\end{itemize}

During the signature operation, the various tags are ordered alphabetically
before the external whitespace is stripped. We do this because we want to
maintain the flexibility of using XML as our share format. XML specifies
that the tags can be in any order, with whitespace between them. On the
other hand, our signature must be a signature of a certain set of
deterministically ordered bits. Thus we compromise by building a string which
comprises each of the tags ordered alphabetically, and then signing that string.