tahoe-lafs/docs/proposed/accounting-overview.txt

= Accounting =

"Accounting" is the arena of the Tahoe system that concerns measuring,
controlling, and enabling the ability to upload and download files, and to
create new directories. In contrast with the capability-based access control
model, which dictates how specific files and directories may or may not be
manipulated, Accounting is concerned with resource consumption: how much disk
space a given person/account/entity can use.

The 1.3.0 and earlier releases have a nearly-unbounded resource usage model.
Anybody who can talk to the Introducer gets to talk to all the Storage
Servers, and anyone who can talk to a Storage Server gets to use as much disk
space as they want (up to the reserved_space= limit imposed by the server,
which affects all users equally). Not only is the per-user space usage
unlimited, it is also unmeasured: the owner of the Storage Server has no way
to find out how much space Alice or Bob is using.

The goals of the Accounting system are thus:

 * allow the owner of a storage server to control who gets to use disk space,
   with separate limits per user
 * allow both the server owner and the user to measure how much space the user
   is consuming, in an efficient manner
 * provide grid-wide aggregation tools, so a set of cooperating server
   operators can easily measure how much a given user is consuming across all
   servers. This information should also be available to the user in question.

For the purposes of this document, the terms "Account" and "User" are mostly
interchangeable. The fundamental unit of Accounting is the "Account", in that
usage and quota enforcement is performed separately for each account. These
accounts might correspond to individual human users, or they might be shared
among a group, or a user might have an arbitrary number of accounts.

Accounting interacts with Garbage Collection. To protect their shares from
GC, clients maintain limited-duration leases on those shares: when the last
lease expires, the share is deleted. Each lease has a "label", which
indicates the account or user which wants to keep the share alive. A given
account's "usage" (their per-server aggregate usage) is simply the sum of the
sizes of all shares on which they hold a lease. The storage server may limit
the user to a fixed "quota" (an upper bound on their usage). To keep a file
alive, the user must be willing to use up some of their quota. A popular file
might have leases from multiple users, in which case one user might take a
chance and decline to add their own lease, saving some of their quota and
hoping that the other leases continue to keep the file alive despite their
personal unwillingness to contribute to the effort.

== Authority Flow ==

The authority to consume space on the storage server originates, of course,
with the storage server operator. These operators start with complete control
over their space, and delegate portions of it to others: either directly to
clients who want to upload files, or to intermediaries who can then delegate
attenuated authority onwards. The operators have various reasons for wanting
to share their space: monetary consideration, expectations of in-kind
exchange, or simple generosity. But the first and final authority rests with
them.

The server operator grants restricted authority over their space by
configuring their server to accept requests that demonstrate knowledge of
certain secrets. They then share those secrets with the client who intends to
use this space, or an intermediary who will generate still more secrets and
share those with the client. Eventually, an upload or create-directory
operation will be performed that needs this authority. Part of the operation
will involve proving knowledge of the secret to the storage server, and the
server will require this proof before accepting the uploaded share or adding
a new lease.

The authority is expressed as a string, containing cryptographically-signed
messages and keys. The string also contains "restrictions", which are
annotations that explain the limits imposed upon this authority, either by
the original grantor (the storage server operator) or by one of the
intermediaries. Authority can be reduced but not increased. Any holder of a
given authority can delegate some or all of it to another party.

The authority string may be short enough to include as an argument to a CLI
command (--with-authority ABCDE), or it may be long enough that it must be
stashed in a file and referenced in some other fashion (--with-authority-file
~/.my_authority). There are CLI tools to create brand new authority strings,
to derive attenuated authorities from an existing one, and to explain the
contents of an authority string. These authority strings can be shared with
others just like filecaps and dircaps: knowledge of the authority string is
both necessary and complete to wield the authority it represents.

webapi requests will include the authority necessary to complete the
operation. When used by a CLI tool, the authority is likely to come from
~/.tahoe/private/authority (i.e. it is ambient to the user who has access to
that node, just like aliases provide similar access to a specific "root
directory"). When used by the browser-oriented WUI, the authority will [TODO]
somehow be retained on each page in a way that minimizes the risk of CSRF
attacks and allows safe sharing (cut-and-paste of a URL without sharing the
storage authority too). The client node receiving the webapi request will
extract the authority string from the request and use it to build the storage
server messages that it uses to fulfill the request.

== Definition Of Authority ==

The term "authority" is used here somewhat casually: in the object-capability
world, the word refers to the ability of some principal to cause some action
to occur, whether because they can do it themselves, or because they can
convince some other principal to do it for them. In Tahoe terms, "storage
authority" is the ability to do one of the following actions:

 * upload a new share, thus consuming storage space
 * adding a new lease to a share, thus preventing space from being reclaimed
 * modify an existing mutable share, potentially increasing the space consumed

The Accounting effort may involve other kinds of authority that gets limited
in a similar manner as storage authority, like the ability to download a
share: things that may consume CPU time, disk bandwidth, or other limited
resources. There is also the authority to renew or cancel a lease, which may
be controlled in a similar fashion.

Storage authority, as granted from a server operator to a client, is not
simply a binary "use space or not" grant. Instead, it is parameterized by a
number of "restrictions". The most important of these restrictions (with
respect to the goals of Accounting) is the "Account Label".

=== Account Labels ===

A Tahoe "Account" is defined by a variable-length sequence of small integers.
(they are not required to be small, the actual limit is 2**64, but neither
are they required to be unguessable). These accounts are arranged in a
hierarchy: the account identifier (1,4) is considered to be a "parent" of
(1,4,2). There is no relationship between the values used by unrelated
accounts: (1,4) is unrelated to (2,4), despite both coincidentally using a
"4" in the second element.

Each lease has a label, which contains the Account identifier. The storage
server maintains an aggregate size count for each label prefix: when asked
about account (1,4), it will report the amount of space used by shares
labeled (1,4), (1,4,2), (1,4,7), (1,4,7,8), etc (but *not* (1) or (1,5)).

The "Account Label" restriction allows a client to apply any label it wants,
as long as that label begins with a specific prefix. If account (1) is
associated with Alice, then Alice will receive a storage authority string
that contains a "must start with (1)" restriction, enabling her to to use
storage space but obligating her to lease her shares with a label that can be
traced back to her. She can delegate part of her authority to others (perhaps
with other non-label restrictions, such as a space restriction or time limit)
with or without an additional label restriction. For example, she might
delegate some of her authority to her friend Amy, with a (1,4) label
restriction. Amy could then create labels with (1,4) or (1,4,7), but she
could not create labels with the same (1) identifier that Alice can do, nor
could she create labels with (1,5) (which Alice might have given to her other
friend Annette). The storage server operator can ask about the usage of (1)
to find out how much Alice is responsible for (which includes the space that
she has delegated to Amy and Annette), and none of the A-users can avoid
being counted in this total. But Alice can ask the storage server about the
usage of (1,4) to find out how much Amy has taken advantage of her gift.
Likewise, Alice has control over any lease with a label that begins with (1),
so she can cancel Amy's leases and free the space they were consuming. If
this seems surprising, consider that the storage server operator considerd
Alice to be responsible for that space anyways: with great responsibility
(for space consumed) comes great power (to stop consuming that space).

=== Server Space Restriction ===

The storage server's basic control over how space usage (apart from the
binary use-it-or-not authority granted by handing out an authority string at
all) is implemented by keeping track of the space used by any given account
identifier. If account (1,4) sends a request to allocate a 1MB share, but
that 1MB would bring the (1,4) usage over its quota, the request will be
denied.

For this to be useful, the storage server must give each usage-limited
principal a separate account, and it needs to configure a size limit at the
same time as the authority string is minted. For a friendnet, the CLI "add
account" tool can do both at once:

 tahoe server add-account --quota 5GB Alice
 --> Please give the following authority string to "Alice", who should
     provide it to the "tahoe add-authority" command
     (authority string..)

This command will allocate an account identifier, add Alice to the "pet name
table" to associate it with the new account, and establish the 5GB sizelimit.
Both the sizelimit and the petname can be changed later.

Note that this restriction is independent for each server: some additional
mechanism must be used to provide a grid-wide restriction.

Also note that this restriction is not expressed in the authority string. It
is purely local to the storage server.

=== Attenuated Server Space Restriction ===

TODO (or not)

The server-side space restriction described above can only be applied by the
storage server, and cannot be attenuated by other delegates. Alice might be
allowed to use 5GB on this server, but she cannot use that restriction to
delegate, say, just 1GB to Amy.

Instead, Alice's sub-delegation should include a "server_size" restriction
key, which contains a size limit. The storage server will only honor a
request that uses this authority string if it does not cause the aggregate
usage of this authority string's account prefix to rise above the given size
limit.

Note that this will not enforce the desired restriction if the size limits
are not consistent across multiple delegated authorities for the same label.
For example, if Amy ends up with two delagations, A1 (which gives her a size
limit of 1GB) and A2 (which gives her 5GB), then she can consume 5GB despite
the limit in A1.

=== Other Restrictions ===

Many storage authority restrictions are meant for internal use by tahoe tools
as they delegate short-lived subauthorities to each other, and are not likely
to be set by end users.

 * "SI": a storage index string. The authority can only be used to upload
   shares of a single file.
 * "serverid": a server identifier. The authority can only be used when
   talking to a specific server
 * "UEB_hash": a binary hash. The authority can only be used to upload shares
   of a single file, identified by its share's contents. (note: this
   restricton would require the server to parse the share and validate the
   hash)
 * "before": a timestamp. The authority is only valid until a specific time.
   Requires synchronized clocks or a better definition of "timestamp".
 * "delegate_to_furl": a string, used to acquire a FURL for an object that
   contains the attenuated authority. When it comes time to actually use the
   authority string to do something, this is the first step.
 * "delegate_to_key": an ECDSA pubkey, used to grant attenuated authority to
   a separate private key.

== User Experience ==

The process starts with Bob the storage server operator, who has just created
a new Storage Server:

 tahoe create-client
 --> creates ~/.tahoe
 # edit ~/.tahoe/tahoe.cfg, add introducer.furl, configure storage, etc

Now Bob decides that he wants to let his friend Alice use 5GB of space on his
new server.

 tahoe server add-account --quota=5GB Alice
 --> Please give the following authority string to "Alice", who should
     provide it to the "tahoe add-authority" command
     (authority string XYZ..)

Bob copies the new authority string into an email message and sends it to
Alice. Meanwhile, Alice has created her own client, and attached it to the
same Introducer as Bob. When she gets the email, she pastes the authority
string into her local client:

 tahoe client add-authority (authority string XYZ..)
 --> new authority added: account (1)

Now all CLI commands that Alice runs with her node will take advantage of
Bob's space grant. Once Alice's node connects to Bob's, any upload which
needs to send a share to Bob's server will search her list of authorities to
find one that allows her to use Bob's server.

When Alice uses her WUI, upload will be disabled until and unless she pastes
one or more authority strings into a special "storage authority" box. TODO:
Once pasted, we'll use some trick to keep the authority around in a
convenient-yet-safe fashion.

When Alice uses her javascript-based web drive, the javascript program will
be launched with some trick to hand it the storage authorities, perhaps via a
fragment identifier (http://server/path#fragment).

If Alice decides that she wants Amy to have some space, she takes the
authority string that Bob gave her and uses it to create one for Amy:

 tahoe authority dump (authority string XYZ..)
 --> explanation of what is in XYZ
 tahoe authority delegate --account 4,1 --space 2GB (authority string XYZ..)
 --> (new authority string ABC..)

Alice sends the ABC string to Amy, who uses "tahoe client add-authority" to
start using it.

Later, Bob would like to find out how much space Alice is using. He brings up
his node's Storage Server Web Status page. In addition to the overall usage
numbers, the page will have a collapsible-treeview table with lines like:

 AccountID  Usage  TotalUsage Petname
 (1)        1.5GB  2.5GB      Alice
 +(1,4)     1.0GB  1.0GB      ?

This indicates that Alice, as a whole, is using 2.5GB. It also indicates that
Alice has delegated some space to a (1,4) account, and that delegation has
used 1.0GB. Alice has used 1.5GB on her own, but is responsible for the full
2.5GB. If Alice tells Bob that the subaccount is for Amy, then Bob can assign
a pet name for (1,4) with "tahoe server add-pet-name 1,4 Amy". Note that Bob
is not aware of the 2GB limit that Alice has imposed upon Amy: the size
restriction may have appeared on all the requests that have showed up thus
far, but Bob has no way of being sure that a less-restrictive delgation
hasn't been created, so his UI does not attempt to remember or present the
restrictions it has seen before.

=== Friendnet ===

A "friendnet" is a set of nodes, each of which is both a storage server and a
client, each operated by a separate person, all of which have granted storage
rights to the others.

The simplest way to get a friendnet started is to simply grant storage
authority to everybody. "tahoe server enable-ambient-storage-authority" will
configure the storage server to give space to anyone who asks. This behaves
just like a 1.3.0 server, without accounting of any sort.

The next step is to restrict server use to just the participants. "tahoe
server disable-ambient-storage-authority" will undo the previous step, then
there are two basic approaches:

 * "full mesh": each node grants authority directory to all the others.
   First, agree upon a userid number for each participant (the value doesn't
   matter, as long as it is unique). Each user should then use "tahoe server
   add-account" for all the accounts (including themselves, if they want some
   of their shares to land on their own machine), including a quota if they
   wish to restrict individuals:

    tahoe server add-account --account 1 --quota 5GB Alice
    --> authority string for Alice
    tahoe server add-account --account 2 --quota 5GB Bob
    --> authority string for Bob
    tahoe server add-account --account 3 --quota 5GB Carol
    --> authority string for Carol

  Then email Alice's string to Alice, Bob's string to Bob, etc. Once all
  users have used "tahoe client add-authority" on everything, each server
  will accept N distinct authorities, and each client will hold N distinct
  authorities.

 * "account manager": the group designates somebody to be the "AM", or
   "account manager". The AM generates a keypair and publishes the public key
   to all the participants, who create a local authority which delgates full
   storage rights to the corresponding private key. The AM then delegates
   account-restricted authority to each user, sending them their personal
   authority string:

    AM:
     tahoe authority create-authority --write-private-to=private.txt
     --> public.txt
     # email public.txt to all members
    AM:
     tahoe authority delegate --from-file=private.txt --account 1 --quota 5GB
     --> alice_authority.txt # email this to Alice
     tahoe authority delegate --from-file=private.txt --account 2 --quota 5GB
     --> bob_authority.txt # email this to Bob
     tahoe authority delegate --from-file=private.txt --account 3 --quota 5GB
     --> carol_authority.txt # email this to Carol
     ...
    Alice:
     # receives alice_authority.txt
     tahoe client add-authority --from-file=alice_authority.txt
     # receives public.txt
     tahoe server add-authorization --from-file=public.txt
    Bob:
     # receives bob_authority.txt
     tahoe client add-authority --from-file=bob_authority.txt
     # receives public.txt
     tahoe server add-authorization --from-file=public.txt
    Carol:
     # receives carol_authority.txt
     tahoe client add-authority --from-file=carol_authority.txt
     # receives public.txt
     tahoe server add-authorization --from-file=public.txt

   If the members want to see names next to their local usage totals, they
   can set local petnames for the accounts:

     tahoe server set-petname 1 Alice
     tahoe server set-petname 2 Bob
     tahoe server set-petname 3 Carol

   Alternatively, the AM could provide a usage aggregator, which will collect
   usage values from all the storage servers and show the totals in a single
   place, and add the petnames to that display instead.

   The AM gets more authority than anyone else (they can spoof everybody),
   but each server has just a single authorization instead of N, and each
   client has a single authority instead of N. When a new member joins the
   group, the amount of work that must be done is significantly less, and
   only two parties are involved instead of all N:

    AM:
     tahoe authority delegate --from-file=private.txt --account 4 --quota 5GB
     --> dave_authority.txt # email this to Dave
    Dave:
     # receives dave_authority.txt
     tahoe client add-authority --from-file=dave_authority.txt
     # receives public.txt
     tahoe server add-authorization --from-file=public.txt

   Another approach is to let everybody be the AM: instead of keeping the
   private.txt file secret, give it to all members of the group (but not to
   outsiders). This lets current members bring new members into the group
   without depending upon anybody else doing work. It also renders any notion
   of enforced quotas meaningless, so it is only appropriate for actual
   friends who are voluntarily refraining from spoofing each other.

=== Commercial Grid ===

A "commercial grid", like the one that allmydata.com manages as a for-profit
service, is characterized by a large number of independent clients (who do
not know each other), and by all of the storage servers being managed by a
single entity. In this case, we use an Account Manager like above, to
collapse the potential N*M explosion of authorities into something smaller.
We also create a dummy "parent" account, and give all the real clients
subaccounts under it, to give the operations personnel a convenient "total
space used" number. Each time a new customer joins, the AM is directed to
create a new authority for them, and the resulting string is provided to the
customer's client node.

 AM:
  tahoe authority create-authority --account 1 \
   --write-private-to=AM-private.txt --write-public-to=AM-public.txt

Each time a new storage server is brought up:

 SERVER:
  tahoe server add-authorization --from-file=AM-public.txt

Each time a new client joins:

 AM:
  N = next_account++
  tahoe authority delegate --from-file=AM-private.txt --account 1,N
  --> new_client_authority.txt # give this to new client

== Programmatic Interfaces ==

The storage authority can be passed as a string in a single serialized form,
which is cut-and-pasteable and printable. It uses minimal punctuation, to
make it possible to include it as a URL query argument or HTTP header field
without requiring character-escaping.

Before passing it over HTTP, however, note that revealing the authority
string to someone is equivalent to irrevocably delegating all that authority
to them. While this is appropriate when transferring authority from, say, a
receptive storage server to your local agent, it is not appropriate when
using a foreign tahoe node, or when asking a Helper to upload a specific
file. Attenuations (see below) should be used to limit the delegated
authority in these cases.

In the programmatic webapi interface (colloquially known as the "WAPI"), any
operation that consumes storage will accept a storage-authority= query
argument, the value of which will be the printable form of an authority
string. This includes all PUT operations, POST t=upload and t=mkdir, and
anything which creates a new file, creates a directory (perhaps an
intermediate one), or modifies a mutable file.

Alternatively, the authority string can also be passed through an HTTP
header. A single "X-Tahoe-Storage-Authority:" header can be used with the
printable authority string. If the string is too large to fit in a single
header, the application can provide a series of numbered
"X-Tahoe-Storage-Authority-1:", "X-Tahoe-Storage-Authority-2:", etc, headers,
and these will be sorted in alphabetical order (please use 08/09/10/11 rather
than 8/9/10/11), stripped of leading and trailing whitespace, and
concatenated. The HTTP header form can accomodate larger authority strings,
since these strings can grow too large to pass as a query argument
(especially when several delegations or attenuations are involved). However,
depending upon the HTTP client library being used, passing extra HTTP headers
may be more complicated than simply modifying the URL, and may be impossible
in some cases (such as javascript running in a web browser).

TODO: we may add a stored-token form of authority-passing to handle
environments in which query-args won't work and headers are not available.
This approach would use a special PUT which takes the authority string as the
HTTP body, and remembers it on the server side in associated with a
brief-but-unguessable token. Later operations would then use the authority by
passing a --storage-authority-token=XYZ query argument. These authorities
would expire after some period.

== Quota Management, Aggregation, Reporting ==

The storage server will maintain enough information to efficiently compute
usage totals for each account referenced in all of their leases, as well as
all their parent accounts. This information is used for several purposes:

 * enforce server-space restrictions, by selectively rejecting storage
   requests which would cause the account-usage-total to rise above the limit
   specified in the enabling authorization string
 * report individual account usage to the account-holder (if a client can
   consume space under account A, they are also allowed to query usage for
   account A or a subaccount).
 * report individual account usage to the storage-server operator, possibly
   associated with a pet name
 * report usage for all accounts to the storage-server operator, possibly
   associated with a pet name, in the form of a large table
 * report usage for all accounts to an external aggregator

The external aggregator would take usage information from all the storage
servers in a single grid and sum them together, providing a grid-wide usage
number for each account. This could be used by e.g. clients in a commercial
grid to report overall-space-used to the end user.

There will be webapi URLs available for all of these reports.

TODO: storage servers might also have a mechanism to apply space-usage limits
to specific account ids directly, rather than requiring that these be
expressed only through authority-string limitation fields. This would let a
storage server operator revoke their space-allocation after delivering the
authority string.

== Low-Level Formats ==

This section describes the low-level formats used by the Accounting process,
beginning with the storage-authority data structure and working upwards. This
section is organized to follow the storage authority, starting from the point
of grant. The discussion will thus begin at the storage server (where the
authority is first created), work back to the client (which receives the
authority as a webapi argument), then follow the authority back to the
servers as it is used to enable specific storage operations. It will then
detail the accounting tables that the storage server is obligated to
maintain, and describe the interfaces through which these tables are accessed
by other parties.

=== Storage Authority ===

==== Terminology ====

Storage Authority is represented as a chain of certificates and a private
key. Each certificate authorizes and restricts a specific private key. The
initial certificate in the chain derives its authority by being placed in the
storage server's tahoe.cfg file (i.e. by being authorized by the storage
server operator). All subsequent certificates are signed by the authorized
private key that was identified in the previous certificate: they derive
their authority by delegation. Each certificate has restrictions which limit
the authority being delegated.

 authority: ([cert[0], cert[1], cert[2] ...], privatekey)

The "restrictions dictionary" is a table which establishes an upper bound on
how this authority (or any attenuations thereof) may be used. It is
effectively a set of key-value pairs.

A "signing key" is an EC-DSA192 private key string, as supplied to the
pycryptopp SigningKey() constructor, and is 12 bytes long. A "verifying key"
is an EC-DSA192 public key string, as produced by pycryptopp, and is 24 bytes
long. A "key identifier" is a string which securely identifies a specific
signing/verifying keypair: for long RSA keys it would be a secure hash of the
public key, but since ECDSA192 keys are so short, we simply use the full
verifying key verbatim. A "key hint" is a variable-length prefix of the key
identifier, perhaps zero bytes long, used to help a recipient reduce the
number of verifying keys that it must search to find one that matches a
signed message.

==== Authority Chains ====

The authority chain consists of a list of certificates, each of which has a
serialized restrictions dictionary. Each dictionary will have a
"delegate-to-key" field, which delegates authority to a private key,
referenced with a key identifier. In addition, the non-initial certs are
signed, so they each contain a signature and a key hint:

 cert[0]: serialized(restrictions_dictionary)
 cert[1]: serialized(restrictions_dictionary), signature, keyhint
 cert[2]: serialized(restrictions_dictionary), signature, keyhint

In this example, suppose cert[0] contains a delegate-to-key field that
identifies a keypair sign_A/verify_A. In this case, cert[1] will have a
signature that was made with sign_A, and the keyhint in cert[1] will
reference verify_A.

 cert[0].restrictions[delegate-to-key] = A_keyid

 cert[1].signature = SIGN(sign_A, serialized(cert[0].restrictions))
 cert[1].keyhint = verify_A
 cert[1].restrictions[delegate-to-key] = B_keyid

 cert[2].signature = SIGN(sign_B, serialized(cert[1].restrictions))
 cert[2].keyhint = verify_B
 cert[2].restrictions[delete-to-key] = C_keyid

In this example, the full storage authority consists of the cert[0,1,2] chain
and the sign_C private key: anyone who is in possession of both will be able
to exert this authority. To wield the authority, a client will present the
cert[0,1,2] chain and an action message signed by sign_C; the server will
validate the chain and the signature before performing the requested action.
The only circumstances that might prompt the client to share the sign_C
private key with another party (including the server) would be if it wanted
to irrevocably share its full authority with that party.

==== Restriction Dictionaries ====

Within a restriction dictionary, the following keys are defined. Their full
meanings are defined later.

 'accountid': an arbitrary-length sequence of integers >=0, restricting the
              accounts which can be manipulated or used in leases
 'SI': a storage index (binary string), controlling which file may be
       manipulated
 'serverid': binary string, limiting which server will accept requests
 'UEB-hash': binary string, limiting the content of the file being manipulated
 'before': timestamp (seconds since epoch), limits the lifetime of this
           authority
 'server-size': integer >0, maximum aggregate storage (in bytes) per account
 'delegate-to-key': binary string (DSA pubkey identifier)
 'furl-to': printable FURL string

==== Authority Serialization ====

There is only one form of serialization: a somewhat-compact URL-safe
cut-and-pasteable printable form. We are interested in minimizing the size of
the resulting authority, so rather than using a general-purpose (perhaps
JSON-based) serialization scheme, we use one that is specialized for this
task.

This URL-safe form will use minimal punctuation to avoid quoting issues when
used in a URL query argument. It would be nice to avoid word-breaking
characters that make cut-and-paste troublesome, however this is more
difficult because most non-alphanumeric characters are word-breaking in at
least one application.

The serialized storage authority as a whole contains a single version
identifier and magic number at the beginning. None of the internal components
contain redundant version numbers: they are implied by the container. If
components are serialized independently for other reasons, they may contain
version identifers in that form.

Signing keys (i.e. private keys) are URL-safe-serialized using Zooko's base62
alphabet, which offers almost the same density as standard base64 but without
any non-URL-safe or word-breaking characters. Since we used fixed-format keys
(EC-DSA, 192bit, with SHA256), the private keys are fixed-length (96 bits or
12 bytes), so there is no length indicator: all URL-safe-serialized signing
keys are 17 base62 characters long. The 192-bit verifying keys (i.e. public
keys) use the same approach: the URL-safe form is 33 characters long.

An account-id sequence (a variable-length sequence of non-negative numbers)
is serialized by representing each number in decimal ASCII, then joining the
pieces with commas. The string is terminated by the first non-[0-9,]
character encountered, which will either be the key-identifier letter of the
next field, or the dictionary-terminating character at the end.

Any single decimal number (such as the "before" timestamp field, or the
"server-size" field) is serialized as a variable-length sequence of ASCII
deciman digits, terminated by any non-digit.

The restrictions dictionary is serialized as a concatenated series of
key-identifier-letter / value string pairs, ending with the marker "E.". The
URL-safe form uses a single printable letter to indicate the which key is
being serialized. Each type of value string is serialized differently:

 "A": accountid: variable-length sequence of comma-joned numbers
 "I": storage index: fixed-length 22-character base62-encoded storage index
 "P": server id (peer id): fixed-length 32-character *base32* encoded serverid
      (matching the printable Tub.tubID string that Foolscap provides)
 "U": UEB hash: fixed-length 43-character base62 encoded UEB hash
 "B": before: variable-length sequence of decimal digits, seconds-since-epoch.
 "S": server-size: variable-length sequence of decimal digits, max size in bytes
 "D": delegate-to-key: ECDSA public key, 33 base62 characters.
 "F": furl-to: variable-length FURL string, wrapped in a netstring:
      "%d:%s," % (len(FURL), FURL). Note that this is rarely pasted.
 "E.": end-of-dictionary marker

The ECDSA signature is serialized as a variable number of base62 characters,
terminated by a period. We expect the signature to be about 384 bits (48
bytes) long, or 65 base62 characters. A missing signature (such as for the
initial cert) is represented as a single period.

The key hint is serialized with a base62-encoded serialized hint string (a
byte-quantized prefix of the serialized public key), terminated by a period.
An empty hint would thus be serialized as a single period. For the current
design, we expect the key hint to be empty.

The full storage authority string consists of a certificate chain and a
delegate private key. Given the single-certificate serialization scheme
described above, the full authority is serialized as follows:

 * version prefix: depends upon the application, but for storage-authority
                   chains this will be "sa0-", for storage-authority version
                   0.
 * serialized certificates, concatenated together
 * serialized private key (to which the last certificate delegates authority)

Note that this serialization form does not have an explicit terminator, so
the environment must provide a length indicator or some other way to identify
the end of the authority string. The benefit of this approach is that the
full string will begin and end with alphanumeric characters, making
cut-and-paste easier (increasing the size of the mouse target: anywhere
within the final component will work).

Also note that the period is a reserved delimiter: it cannot appear in the
serialized restrictions dictionary. The parser can remove the version prefix,
split the rest on periods, and expect to see 3*k+1 fields, consisting of k
(restriction-dictionary,signature,keyhint) 3-tuples and a single private key
at the end.

Some examples:

 cert[0] delegates account 1,4 to (pubkey ZlFA / privkey 1f2S):
  sa0-A1,4D2lFA6LboL2xx0ldQH2K1TdSrwuqMMiME3E...1f2SI9UJPXvb7vdJ1

 cert[0] delegates account 1,4 to ZlFA/1f2S
 cert[1] subdelegates 5GB and subaccount 1,4,7 to pubkey 0BPo/06rt:
  sa0-A1,4D2lFA6LboL2xx0ldQH2K1TdSrwuqMMiME3E...A1,4,7S5000000000D0BPoGxJ3M4KWrmdpLnknhJABrWip5e9kPE,7cyhQvv5axdeihmOzIHjs85TcUIYiWHdsxNz50GTerEOR5ucj2TITPXxyaCUli1oF...06rtcPQotR3q4f2cT







== Problems ==

Problems which have thus far been identified with this approach:

 * allowing arbitrary subaccount generation will permit a DoS attack, in
   which an authorized uploader consumes lots of DB space by creating an
   unbounded number of randomly-generated subaccount identifiers. OTOH, they
   can already attach an unbounded number of leases to any file they like,
   consuming a lot of space.