NS specification, version 1.1

This is a multi-part message in MIME format.
--------------080908090208030909030303
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

The attached file contains the completed specification for the naming service, 
version 1.1. The client API will be released by Thursday.

wiht

--------------080908090208030909030303
Content-Type: text/plain;
 name="ns_spec_1_1.txt"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="ns_spec_1_1.txt"

Specification of Naming Service for the I2P Network
Version 1.1
September 16, 2003

Contents
--------
1. Introduction
2. Terminology
3. Client software for naming service
4. Who operates naming servers?
5. Naming server setup
6. Information provided by naming service to clients
7. Storage of entity information by naming servers
8. Certification Authority (CA)
9. Scenarios
   a) Client adds an entity record to a naming server
   b) Client changes its entry on a naming server
   c) Naming server becomes unavailable
   d) Naming server joins network
10. Data structures
11. Message types and structures
   a) Query (request) messages
   b) Response messages
   c) Administrative messages
   d) Error messages
12. Conclusion

================================================================================


1. Introduction

Communication between two destinations on the I2P network can occur only if
one destination knows how to contact the other. In other words, the sending 
destination must know the contact information of the receiving destination to
communicate. This information has to be given to the sending destination before
communication can occur. What if the destination to which to send data is not
known, but a user of the I2P network knows that he or she wants to contact a
certain person and establish an instant messaging session?

The naming service application (abbreviated NS), running over the I2P network,
solves this problem. If user X wants to speak with user Y via Instant Messenger,
user X's IM client uses naming service client software (described in section 3
of this specification) to look up user Y using a known name server and obtain
user Y's contact information. If user Y does not have IM capability, the NS
will inform user X of this fact. Users (or entities, as they are called in this
document) who want to simplify being contacted by others can optionally register
with a name server, which others can then use to look them up. Now, instead of
having to type in user Y's destination, user X will be able to type simply
"im.user Y" as the destination to connect to.

The naming service, as specified below, has several capabilities. Entities
can register with it, add services they provide to their records, and modify
or delete these records. Records are signed with the entity's public key so
that only the entity establishing the record is able to modify it. The entity
is responsible for updating the record if the record changes. Other entities
can search for that entity's record and the services it provides.

This version of the naming service specification tries to address the weaknesses
of the previous version. The naming service as previously described can be
attacked in several ways, such as by adding many new naming servers to the
network at once. This increases the load on existing naming servers to a great
degree, denying service to clients. This version of the specification also
addresses omissions and unclear wording in the previous version. The goal of
this version of the specification is to make it possible to implement the
naming service software.


2. Terminology

This section defines the words and expressions needed to understand this
document. Some of the definitions below are specific to the naming service,
and others are general definitions. The words and expressions appear elsewhere
in this document; this section clarifies their meaning.

I2P network -- as proposed by jrand0m, this is the network of computers on top
of the existing Internet network. Communication occurs by sending messages
between participating computers running special software.

destination -- a node in the I2P network that sends or receives messages, but
does not forward them for other nodes. It is the starting or finishing point of
the path along which a message is sent.

local router -- a routing node in the I2P network, which forwards messages for
the user to other nodes in the I2P network. The naming service software will
use the local router to send out and receive messages.

user -- the agent (usually human being) using the I2P network or the naming
service to retrieve information or contact other users.

naming server -- the destination users send messages to; it runs the naming
service software.

naming service -- the software allowing users to retrieve information about
other users. This software responds to the messages sent to the naming server.

naming server group -- a group of naming servers sharing the same CA.

CA (certificate authority) -- role of the naming service, responsible for the
registration of entity names.

entity -- internal representation of a user's information by the naming service.

entity name -- a name of 1-20 characters long, containing letters, numbers,
spaces, and underscores. It may not begin with a space. An example is "user_x".
This is the way to identify and look up a user's record with the naming service.

entity record -- contains the entity name and a list of services the user
provides. This is public information, available to anyone who seeks it.

service -- a method of contact a user provides to other users. For example,
instant messaging and IRC are services.

client -- the software users run to communicate with naming servers. It is
easier to run this software than to craft messages to the naming service
manually.

Denial of Service (DOS) attack -- making many queries to a given server at
the same time, with the purpose of making the server's resources unavailable
to other users.

operator -- the human being running the naming service software on his or her
computer and making the naming server available to the public.

authoritative server -- role of the naming service, stores master records for
entities, and gives authoritative responses for queries about an entity.

backup server -- role of the naming service, stores backup records for
entities, and also gives responses for queries about an entity.


3. Client software for naming service

A naming service by itself, without clients, would be useless. Information
could be stored, but not retrieved. That is why the naming service software
includes a client component. This component is named "nsclient". Actually,
there will be an API which programs can use to make queries to naming servers.
The underlying mechanism will read a configuration file indicating the server to
query, will use the I2P network to obtain the results, and will pass the results
back to the caller. The underlying mechanism will also read the destination
address for the local router to contact from a file.

In order for the API to work, however, the nsclient program needs to be run
prior to querying servers. The nsclient program will ask the user for the
destination of a local router, and for the directory to use to cache retrieved
results and store settings. After the user enters this information, he or she
will have the choice of registering an entity name with a naming server. Doing
so is optional. If the user chooses to do this, a key will be generated to
sign entity record submissions with, after which the user will be asked for
the information needed to submit a record to an entity record. The user will
then have to specify a naming server to submit the request to, and the
nsclient program will send the registration message to that server.

What if the user has no programs to run which uses the API to query servers, or
wishes to run queries directly? The nsclient program also permits the user to
do this. It will contain a subprogram, which uses the API (described in a
separate document to be released shortly, nsapi.txt) to perform the queries
and display the results.

To modify a record, the user can rerun the nsclient program. Then, the user
can choose a menu option for modifying the record. The nsclient will assist
the user in this by asking a series of questions, and using the answers to
generate a record modification message to a naming server. The program will
know which entity record to modify because it stores the entity record that
was originally submitted in the directory the user initially specifies. This
directory is also used to store a server listing file, which the user can
modify. This is a list of known naming servers, supplied with the program.


4. Who operates naming servers?

The previous version of this specification allowed anyone to run the naming
service software. Malicious users of the I2P network could then add multiple
servers to the group of naming servers at once and cause a denial of service
to users as the new naming servers were added. That is why the policy for adding
a naming server to a group of naming servers is being made more restrictive.

Anyone who wishes to run the naming service software may do so, either alone or
as part of a group. Typically, a naming server will be a member of a group of
naming servers. It is possible to have a group with a single server, but this
document describes the more common scenario with multiple servers in a group.
My vision is that there will be multiple groups of naming servers running at
the same time on the I2P network. At this time, no provision is being made for
groups' joining together to form a larger group or for hierarchies of groups.

The advantages of having a group of servers are redundancy (having backup
servers if a naming server fails) and distributing the storage of entity
information. Since an entity record can be as large as several kilobytes, a
single naming server might not be able to store information for all the
entities that want to register with it. Groups of servers also share a single
CA (see definition above), which registers entity names for the whole group.

Anyone who wishes to run a naming service should make a commitment to do so. A
computer running the NS software should have a fairly stable and fast (i.e.
faster than modem) connection to the Internet. Also, the person running the NS
software should commit at least 6 megabytes of hard disk space to storing entity
records. The person running the NS software should also be contactable by e-mail
or other means.

When a naming server wishes to join a group of naming servers, its operator
contacts the operator of one of the servers already in the group. The group
members then discuss the request, and approve or reject it. I suggest a policy
of doing so unanimously, but this can be done by majority of the members of
the group. The group's operators will set the policy for joining the group. The
human moderation of the additions to a group of servers should make it harder
for malicious operators to join a group. Members of a group can also expel one
of the members from the group, and again I suggest they do so unanimously.


5. Naming server setup

Instead of editing a configuration file the person wishing to run a naming
server will run a program called "nssetup". It will create the configuration
file and fill it with appropriate settings. It will also create the directory
structure needed to store entity records on the naming server. The program is
also run when joining or leaving a group of naming servers.

The first part of the setup is to establish a destination and publish its lease
on the I2P network. Assuming the naming service operator also administers an
I2P router, the router needs to be set up first. Then, the nssetup program
creates a destination (generating the public and signing keys and taking the
other steps necessary) and publishes a destination lease with the router. It
also asks the operator how much hard disk space to make available to the naming
service, and the minimum and maximum size of the queue for user requests. After
this step, settings are saved to the configuration file, and the naming server
is available to serve requests from clients.

The second part of the setup is making the server available to clients. The
operator should either operate the naming server alone or join a group of
naming servers. The nssetup program will present the operator of a naming
server with this choice. If the operator chooses not to join a group, there is
another choice to be made, whether to permit others to join the group. If the
operator allows this, his or her contact information will be asked by nssetup,
to give to those wishing to join the group. After this, nssetup exits, and the
operator can start the naming service software (called simply "ns"). The
operator is then responsible for announcing this naming server's availability
to other users of the I2P network.

When joining a group, the setup program behaves differently. It prompts the
operator to enter the contact information for a server in the group to join. It
then queries that server for the group's contact information (e-mail or other
means, as specified by the person creating the group). The setup program
receives and displays this information, then exits. Next, the operator seeking
to join the group must contact it and request to join the group. I recommend the
policy of notifying the operator of both rejection and approval, but a different
policy can be set by the group, such as notifying the operator of approval
within a week or not responding at all. If rejected, the operator can try to
join another group, or can rerun the setup program and start a group. The server
operator for the CA in the group runs the nssetup program if the request is
accepted, and generates a random confirmation number and a timestamp. These are
e-mailed (or sent by other means) back to the new group member. The new group
member then runs the nssetup program again, and enters this information. Then,
he or she can run the "ns" software application, and will be part of that group.


6. Information provided by naming service to clients

The naming service software allows lookup of three types of information. The
first type is information about the naming service itself. The second is a list
of all the entities that provide a particular service. The third type is
information about a particular entity or a service it provides. A request to the
naming service has the format "service.entity.group", with dots as separators in
the query. No partial matching of names (such as "ab*" for an entity name) is
allowed, and the group name must be entered in each query.

The first type of query has the format "*.*.group". This has not been stated
explicitly above, but each group of naming servers will have a name. When
receiving such a query, a naming server will respond (if the query is for its
group) with contact information for the CA in the group, its public key and
its operator contact information, as well as the number of servers in the group
and the group's name if the group field of the query was also a star.

The second type of query has the format "service.*.group". This allows clients
to find out which entities provide a particular service. For example, "im.*.g1"
will return all the entities allowing Instant Messenger connections in group g1.
The services which can be searched for are defined in section 10.

The third type of query has the format "*.entity.group" or, for one of the
services, "service.entity.group". This will probably be the most common type of
query, and will return the contact information for a particular service and
group, or all the information about an entity, including all the services it
provides and their contact information.


7. Storage of entity information by naming servers

Each naming server in a group of naming servers will store a part of the
information about all entities. It will store the contact information for the
CA in the group (described in the next section), lists of entity names for each
service the naming service software recognizes, and some entity records. If a
user contacts it for an entity record it does not have, it will forward the
request to the server which does have it (it will know which server to contact).

Think of the entities stored by a name server group as a list of entity names.
The allowed first characters of entity names (underscore, digits 0 to 9, and
letters a to z and A to Z) form a domain that can be divided into subdomains.
One possible division is to have two subdomains, all letters and all other
characters. Each name server will store entity records matching one of the
subdomains; for example, one server could store all the entities whose names
begin with the letters m through p. The whole group will store all the records
in this domain.

Actually, each naming server has four roles. Its primary role is as an
authoritative server for a set of entity records corresponding to one of the
subdomains of entity names. In this role, the naming server is the server the
client contacts to change a record or delete it. It also answers queries for
the entities it is responsible for. There may be a small delay between an
entity's record update on the authoritative server and the update on the
backup server, but the authoritative server will minimize this delay by
copying updates to the backup server as soon as records are updated.

The second role is as a backup server for another set of entity records. This
second set must be from a different subdomain of entity names. Each backup
server knows what its master (authoritative) server is; the master server
communicates with its backup server when a record has changed, and provides it
with updates to records. When an authoritative server becomes unavailable, the
backup server assumes the role of the master server for that subdomain, and
selects a new backup server for itself, so that again there will be two copies
of the entity records. The backup server also answers queries for the entities
it stores as the backup server, without checking the authoritative server for
whether the record has been updated.

The third role of a naming server is being a caching server. For example, if a
client asks for the record of the user "blah" but this server in a group does
not have that record, the naming server forwards that request to the
authoritative server for that subdomain of entity names. Upon receiving a
response, it caches the response and returns the query result to the client. If
another client then requests the same record, it can now return it without
consulting the authoritative server. The fourth role of the naming server is to
serve as a CA for the group, as described in the next section. The CA is
responsible for adding entity names stored by the group.

The actual storage of entity records will be in files on the hard drive. The
naming servers will, in the directory specified for entity record storage, have
a file for each type of service. This file will contain the entity names of
all the entities providing that service. In addition, there will be three
subdirectories: "master", "backup", and "cache", corresponding to the roles
described above. Each of these subdirectories will have a file per entity
record, storing that entity's information. These files will be added, modified,
and read as necessary by the naming service software.

The naming service must respect the limits on hard drive space set for it by
the operator. It will periodically check how much space it is filling, and will
respond to filling the space up. If that happens, it will at first try deleting
the records it serves in its role as a caching server. If its master and backup
record caches take up that space, though, it will tell the CA for the group that
it is exceeding its limits. The CA will then reallocate the subdomains, if
possible, to address the problem. Also, a message will be put into the daily
log kept under the "logs" subdirectory, and the operator can re-run the nssetup
program to increase space allocated to the naming service. If all the space
fills up on all the naming servers in the group, the CA will stop accepting new
entity registrations.


8. Certification Authority (CA)

The Certification Authority (CA) role of the naming service is fulfilled by one
and only one naming server at a time. Initially, this is the single server in
the group. As a naming server group grows, the first server continues to be the
CA for the group. However, it designates a backup CA, which becomes the primary
CA if the CA becomes unavailable due to a hard drive crash or leaves the I2P
network. The CA stores the list of entity names for the entity records stored
by the group, as well as the time stamps of when they joined the network. This
information is stored in addition to the entity records the naming server
stores; a CA is also an authoritative and a backup server at the same time.

The main task of the CA is to process requests by entities to store their
records with that group. Clients send these requests, and the CA looks up the
names of entities it already has records for. If the entity name in the request
exists, the request is rejected and an appropriate message is sent back to the
client. If not, the CA generates an approval message, which it digitally signs,
containing a timestamp (in UTC, not the local timezone) of when the request
was processed. The CA stores the new entity name and timestamp for it, to use
when responding to future requests.

A note should be made about the CA's signing records. There will be a keypair
of a public and a private key for the group, with copies stored on every
server that is a member of the group. The private key will be stored in
encrypted format, and loaded into memory when the naming server becomes the CA
for the group. This key will be used by the CA to sign entity registration
requests.

A secondary task of the CA is to keep track of the naming servers available at
any given time. As described earlier, a CA generates a random ID number for each
naming server in the group. After joining the I2P network, each naming server
announces its availability to the CA, with its confirmation number in the
message. The CA then knows that the naming server is online and can process
requests.

When a naming server is unavailable on the I2P network, there are several ways
this is found out. The first way is if an authoritative server cannot contact
its backup server. Since every naming server has a designated backup server,
this will detect the outage, but possibly after some time has passed. The second
way is if the CA cannot contact its backup CA. The third way is if a server, in
its role as the caching server, cannot contact the authoritative server. The
backup CA will periodically contact the CA, and will assume the CA role if it
receives no response for three consecutive queries. Finally, any naming server
failing to contact the CA will notify the backup CA. When a naming server
detects another naming server has failed/is not on the I2P network, it must
notify the CA.

The third role of the CA is to divide subdomains of the entity name list to
different naming servers. Initially, the single naming server in the group will
store all the entity records (space permitting). When other naming servers join
the group and are available, a subdomain reallocation occurs. The CA designates
which naming servers will store which subdomains and the respective entity
records. The CA sends a message with a new subdomain-to-server mapping to all
the naming servers, and they respond by copying entity records according to the
mapping. For example, when a second naming server joins the network, and is
assigned the entity records for letters a-z and digits 0-5, the first naming
server in the network copies its authoritative records to the new server. It
also moves them to its cached directory. The mapping also contains the backup
servers for each authoritative server. The more naming servers there are in
the group, the less records have to be moved within the group during each move.

When a naming server becomes unvailable, the CA determines a new mapping of
subdomains-to-servers, and broadcasts it to the naming servers. The backup
server becomes an authoritative server for the records it had previously as a
backup server. Then, since it cannot be only an authoritative server, it uses
the new mapping to send some records to a new backup server. Another server in
the group sends it records to back up, etc., until the reallocation of records
is complete. The CA also detemines a new mapping when one of the servers
reports that it has no more hard drive space.


9. Scenarios

This section describes what happens when common tasks are performed by clients
and naming servers. Specifically, it describes the sequences of events that
happen. The scenario for an information query is not described in detail
because it is a fairly simple scenario. A query is answered by the
authoritative or backup server directly, or by a caching server after querying
the primary server.

   a) Client adds an entity record to a naming server

Clients add and modify records through the nsclient program described in
section 3 of this document. It sends record addition and modification requests
to known name servers. For a request to be sent, the destination of any naming
server in a group of naming servers needs to be known. This destination can
either be typed by the user or read from a file. The nsclient program then
sends the request, signed by the user's private key.

When a naming server receives such a request, it either answers the request
(if it is the CA for the group at the moment) or forwards it to the CA. If the
CA cannot process the request because it is busy, its response will be a
message telling the client to try later. If the entity name the user requests
has already been registered, the CA responds with a message to that effect.
The nsclient program will then give the user the choice of trying to register
again with a different entity name. If, however, the request is approved, the
CA makes an entry in its records with that entity's name and a timestamp for
the date when the approval was made. Its response to the client is a message
with a certificate for the user's public key, signed by the CA's private key.
The nsclient software then sends the record, including this certificate, to
the name server the CA tells it to send the record to in the response.
That server then checks the certificate, then checks that the record is signed
with the public key for the user, and stores the data. It also propagates it
to the backup server.

Whatever the response by the CA, it is signed with the CA's private key,
verifiable by obtaining its public key. If the user does not have the CA's
public key, the nsclient software obtains it from the known server before
sending the request, and then verifies the response.

   b) Client changes its entry on a naming server

Modifying an entry is not as complicated as adding it. The CA is not involved
in modifying an entry. The user runs the nsclient program, which displays the
locally stored copy of the entity record. The program then allows the user to
add or delete services to the record, and saves the modified record. Just the
modifications of the record are then signed with the user's private key, and
the CA's signature on the public key is also sent in the request to a member
of the same group of servers with which the entity name was registered.

The request reaches either the authoritative server for that entity name, or
another member of the group of naming servers. If the latter occurs, the
request is forwarded to the appropriate server. The authoritative server then
checks the signature on the request, and applies the modifications to the
entity's record. It then sends the modified record to the backup server. The
naming server will respond to the client that it applied the modifications,
or that it is too busy to do so. It will not respond in case of failure to
check the signature on the request.

   c) Naming server becomes unavailable

For the purposes of this specification, unavailable does not mean that there
are delays in messages' reaching their target name servers. Unavailable means
that a server completely leaves the Internet, and hence the I2P network. The
unavailability could be caused by a hard drive crash, a disconnection of the
name server operator's Internet sercie, or the operator shutting down the name
server software. The unavailability of a naming server could last from minutes
to days, and the failure of many servers can drastically affect the group.

As described in section 8 on the Certificate Authority, the CA for the group
will be notified quickly if any naming server becomes unavailable. The CA then
recalculates a mapping of entity names to authoritative naming servers. It
sends out a new mapping to all the naming servers in the group, and they
transfer records until there is again a backup server for every authoritative
server. Should the CA itself fail, the backup CA announces itself as the
primary CA to the group, and designates another group member as the new backup
CA. Also, the CA (or backup CA assuming the role of primary CA) logs the fact
that the server has left the group.

Of course, while entity records are being copied from a former backup server
to a new backup server and the naming servers readjust the entries they are
responsible for, queries are still coming to naming servers from users. The
readjustment of entries within the group takes priority over serving user
queries in this case. The naming servers may respond with more messages that
they are busy than usual until the entity records are finished being copied.

   d) Naming server joins I2P network

This section describes what happens when the "ns" software runs. This section
assumes that the setup program described in section 5 has been run, and the
configuration settings for the naming service software exist. If they do not,
the program exits and reminds the operator of the naming service to run the
setup program.

Each server has, stored in its records, a confirmation number sent to it when
it joined the group. When it joins the I2P network and is available to clients
and other naming servers, it sends an availability message to the CA for the
group, or one of the peers, which forwards the request. The CA checks the
number against its records (also maintained by the backup CA), and asks the
naming server what records it holds, if any, from the last time it was the
member of a group. On the basis of this information, it recalculates a mapping
of entity names, and sends out the new mapping to all the members of the
group. Once again, a readjustment occurs as some records are moved between
naming servers, and then the naming server proceeds to serve queries as usual.

What if a naming server returns to the I2P network after being unavailable?
If it was formerly a CA, it does not assume CA status, but becomes a regular
naming server. Also, the naming server does not delete the records it had
before as an authoritative or backup server, but it does delete the records
it had cached. The reason it does not delete the records is that it is
possible for both an authoritative and a backup server to fail within a
small period of time. Until either one returns to the I2P network, a genuine
loss of record data occurs as far as the remaining members of the group are
concerned. When the former server returns to the I2P network, its records are
reintegrated with those now held within the group, and lost data is restored.


10. Data structures

Since the NS software will be communicating over the I2P network, several data
structures used by the I2P network are pertinent to this application. The most
important ones are the Destination data structure and the data structures for
sending data between destinations. The NS software will utilize these data
structures for communications between clients and naming servers, compatibly
with the appropriate I2P specifications. It will also use the Certificate
data structure, as explained below.

There are several data structures in this software. First is the query data
structure used by clients, which looks as follows:

Query
   service -- the service to search for, an integer
   entity -- entity name, a string of 1-32 characters
   group -- group name, a string of 1-32 characters

The integer constants for the services recognized by the naming service are
the following. These are used in the query structure above to find out whether
an entity provides a given service. A query containing numbers other than
these is erroneous, and is discarded.

1 = Instant Messaging (IM)
2 = File Transfer Protocol (FTP)
3 = Internet Relay Chat (IRC)
4 = World Wide Web (WWW)

The group name is a string, as specified above, but it is not used only in the
query structure. It is also stored on each naming server in a group, and can
be sent to a user.

An entity record, another important data structure, contains several fields.
But first, the local Destination structure used to send request contains three
important fields. They are the public and private keys for the user and the
Certificate field. The latter contains the certificate the CA gives to the
user upon successful registration of an entity record. The private key is
used to sign messages. This may actually be called a PublicSigningKey in the
I2P specification. The entity record contains the following fields (the fields
after signature are optional):

Entity_Record
   name -- the entity's name
   pubKey -- the public key, used to verify signature
   signature -- signature of the other fields, except for pubKey
   service_1 -- integer indicating service available for this user
   destination_1 -- corresponding destination
   ...
   service_n
   destination_n

Several data structures are used by the naming servers. First, there is the
CA's public and private key. Then there is the hard drive limit for a naming
server, which is an integer indicating the number of bytes for the limit.
Third is the (possibly empty) list of all users for each service as defined
above. For example, im.txt, for the IM service, might look like this:

a
blah
user_x

It lists the users, one per line, who provide the IM service. The other data
structures are as follows.

Group List stored by CA (group_list)
   ns_1 -- destination for naming server 1
   conf_1 -- confirmation number
   time_1 -- timestamp of when server first joined group
   ...
   ns_n
   conf_n
   time_n

rpq (Request Priority Queue)
   message_1 -- the first request message in the queue
   priority_1 -- the message's priority
   ...
   message_max -- the last request message in the queue
   message_max -- its priority

It should be noted that the queue could be empty, partially filled, or fully
filled at any time. At this time, the priority is ignored, and the first
message to reach the server will be processed first. Starting with version 1.2
of this specification, though, the message priorities will be taken into
account.

The final data structure is the entity name to naming server mapping. This is
sent by the CA for the group to the other group members. Within the message,
roles can be CA (designated by integer 1), authoritative server (designated by
integer 2), backup server (designated by integer 3), or backup CA (designated
by integer 4). An example follows, where there are three servers in a group.
The CA and backup CA are specified first, then the authoritative and backup
servers.

Server          Role    First entity name       Last entity name
server_1        1       [none]                  [none]
server_3        4       [none]                  [none]
server_2        2       abe                     foma
server_2        3       1stname                 999
server_1        2       friend                  user_x
server_1        3       abe                     foma
server_3        2       1stname                 999
server_3        3       friend                  user_x


11. Message types and structures

The messages sent between clients and naming servers, and between naming
servers, can be divided into four categories. First are the queries, or
requests, mostly emanating from clients to servers. Then there are responses.
Third are the administrative messages, mostly from the CA to other naming
servers. Finally, error messages form the fourth category. Query message
names are prefixed with "qry", response message names with "rsp",
administrative message names with "adm", and error message names with "err".
Each of the message structures below includes information on the circumstances
in which it is sent, from whom and to whom it is sent, and its fields. Since
by design of the I2P network, naming servers cannot know where to send back
responses, a field "back" is included as necessary in messages (not shown),
which contains the destination to send the response to.

   a) Query (request) messages

qryLookup
From: client or naming server
To: naming server
when: When looking up information about other clients.
Fields:
   search -- the Query data structure indicating what to search for

qryAddRecord
From: client
To: first CA, then naming server if CA approves
When: When registering an entity name.
Fields:
   er -- entity record data structure, with only the entity name filled in
   cert -- when sending to naming server, certificate from CA for this entity

qryModifyRecord
From: client
To: naming server
When: When modifying a record -- adding or deleting a service.
Fields:
   er -- the modified entity record data structure
   cert -- when sending to naming server, certificate from CA for this entity

qryContacts
From: client or naming server
To: naming server
When: When the group's contact information needs to be known.
Fields: none (other than the "back" field)

qryServerAvailable
From: naming server
To: CA or another naming server (if so, forwarded to CA)
When: naming server connects to the I2P network and is ready to serve requests
Fields:
   conf -- confirmation number for the server

qryRecordsStored
From: CA
To: naming server
When: CA responds to the qryServerAvailable message with this request
Fields: none

   b) Response messages

rspLookupGroup
From: naming server
To: client
When: When responding to a query of type "*.*.group"
Fields:
   name -- group's name
   ca_dest -- destination for CA in group
   ca_key -- CA's public key
   contact -- a string specifying CA operator's contact information
   num_servers -- the number of servers in the group

rspLookupEntity
From: naming server
To: client
When: When responding to a query of type "*.entity.group"
Fields:
   er -- entity record for the entity requested. If a particular service was
   specified in the request, the entity record will be returned with only the
   fields for that service, and no others.

rspLookupList
From: naming server
To: client
When: When responding to a query of type "service.*.group"
Fields:
   numResults -- number of entities matching the query; could be zero
   entity1_name -- name of the first entity providing the service
   entity1_dest -- corresponding destination for that entity
   ...
   entityn_name
   entityn_dest

rspRecordAdded
From: naming server or backup server
To: client or naming server (if from backup server)
When: a record has been successfully added
Fields:
   name -- entity name for which record was added

rspRecordModified
From: naming server or backup server
To: client or naming server (if from backup server)
When: a record has been successfully modified
Fields:
   name -- entity name for which record was added

rspContacts
From: naming server
To: naming server or client
When: When responding to a qryContacts message
Fields:
   contact -- a string with the contact information for the group

rspAddRejected
From: CA
To: client requesting record addition
When: when the entity name has already been registered.
Fields:
   name -- string with entity name already taken

rspAddApproved
From: CA
To: client requesting record addition
When: when the entity name can be added
Fields:
   sig -- CA's signature
   cert -- Certificate CA issues to client, for proving client is registered
   time -- timestamp of when the record was added

rspRecordsStored
From: naming server
To: CA
When: When the CA requests a listing of records the naming server stored
previously (prior to disconnection from network)
Fields:
   first_auth -- entity name for first record stored as authoritative server
   last_auth -- entity name for last record stored as authoritative server
   first_bak -- entity name for first record stored as backup server
   last_bak -- entity name for last record stored as backup server

   c) Administrative messages

admNewServer
From: CA
To: Backup CA
When: new server joins group, and is approved.
Fields:
   dest -- the destination for the new server
   time -- the time it joined the group
   conf -- its confirmation number

admRecordAdded
From: authoritative naming server
To: backup naming server
When: a record has been added to the authoritative server
Fields:
   name -- entity name for which record was added
   er -- the entity record to store

admRecordModified
From: naming server or backup server
To: client or naming server (if from backup server)
When: a record has been modified on the authoritative naming server
Fields:
   name -- entity name for which record was added
   er -- entity record with modifications

admNewMapping
From: CA or backup CA
To: all naming servers
When: when there is a change in which naming server stores what records,
or when the primary CA fails
Fields:
   signature -- this message is signed by the CA
   mapping -- the mapping data structure from the previous section

admPing
From: backup CA
To: CA
When: sent periodically to check that the CA is still on the I2P network.
Fields: none

admPong
From: CA
To: backup CA
When: responding to an admPing message if the CA is on the I2P network
Fields: none

admRecordTransfer
From: former authoritative server for a set of records
To: new naming server for a set of records, or new backup server
When: In response to an admNewMapping message
Fields:
   numrecords -- number of records transferred
   er1 -- first entity record
   ...
   ern -- last entity record

d) Error messages

errBusy
From: naming server or CA
To: naming server or client
When: when the server or CA is too busy processing other requests
Fields: none

errWrongGroup
From: naming server or CA
To: client or naming server
When: when a request is sent for information about a different group, or
when a client sends a request to join a different group by mistake.
Fields: none

errNoSuchEntity
From: naming server
To: client
When: when responding to a query of the type "*.entity.group" and there
is no entity with the desired name.
Fields:
   name -- entity name which does not exist in the records for this group

errLimitReached
From: naming server
To: CA
When: when no more hard disk space is available for record storage
Fields: none

errRecordStorage
From: naming server or CA
To: client
When: when client wants to add or modify record but there is no hard drive
space for it, or when CA knows all the naming servers have no more space and
client wants to register an entity name
Fields: none


12. Conclusion

During the writing of this document, the author had ethical qualms about what
he is doing. Does creating this software aid criminals who might use the I2P
network for communicating with each other? Is it aiding bank robbers,
real terrorists, or at least possibly spammers? Since the users of the I2P
network cannot be known, by design, these are possibilities for who the users
of the I2P network will be. After considering this, the author has decided to
proceed with writing this document and creating the software. The naming
service will not aid these malicious users significantly, as opposed to not
having a naming service at all. Also, the users of the naming service cannot
be distinuished or controlled. And since the naming service will benefit the
majority of users with good intentions, its benefits outweigh the drawbacks of
providing users with the naming service.

If this document contains any errors in spelling or grammar, unclear wording,
or omissions, please let the author know. Sugestions are also welcome for
improving the naming service described in this specification, and for
addressing new security weaknesses that may have been introduced in this
version of the specification. The errors will be corrected in version 1.2 of
the specification. Version 1.2 of the specification will also contain a
section on the algorithms used to prioritize requests in a naming server's
request queue and to map entity names to the naming servers storing records.
The plan is to begin implementing the naming service software, updating it as
the specification is revised, after this release of the specification. Also,
an API will be released for clients to use in querying naming servers prior
to the release of version 1.2 of this specification.

--------------080908090208030909030303
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
iip-dev mailing list
[email protected]
http://lists.invisiblenet.net/mailman/listinfo/iip-dev

--------------080908090208030909030303--