ERights Home elib / distrib / vattp 
Back to: SSL & Data-Pluribus No Next Sibling

The Vat Location Service

Author: Bill Frantz (


The Vat Location Service (VLS) maintains an association between the vat IDs of client vats, and the IP address and port by which they may be reached. (A vat is the part of the E implementation that has a unique network identity.)

Related Documents

See Comm System Overview for information about the VatTP communicaton system.

See E Data Comm System Through Firewalls for some thoughts on working through firewalls.


The basic requirements of the VLS are: address association, entry aging, DOS protection, and firewall traversal
  • Address association: For each vat which has recently registered with the VLS, the VLS will maintain the netword address(es) at which that vat may be located.
  • Entry aging: The VLS will conserve storage by eliminating associations which have not been refreshed within a timeout interval.
  • DOS protection: The VLS will protect against certain kinds of denial or service (DOS) attacks. Specifically, it will require all registrations to have a serial number, and be digitally signed by the VAT's private key. (Note that the digital signatures do not always have to be checked). It will also ensure that clients have performed a certain amount of computation by requiring "hash cash" for certain registrations.
  • Firewall traversal: The VLS will aid in operating across firewalls by performing certain IP Address translations.


The VLS will be a stand-alone Java program. Detailed architecture TBD...

Basic registration logic flow

  1. A vat wishing to register with the VLS builds a connection to it and and sends a registration message.
  2. The VLS reads the registration message and checks if it already has a registration for the vat. If it does not, the VLS builds a new registration which includes the VatID, the time of registration, the IP Address, and sufficient information to check the signature, completing processing of the message.
  3. If there is already a registration for the vat, and the IP Address in the message is the same as in the registraton, then the VLS updates the time of registration, and the signature information, completing processing of the message.
  4. The VLS sends the client a request for hash cash consisting of a 160 bit mask M with a configurable number of bits on and a random 160 bit number N. The client computes a SHA1 value V such that (SHA1(V) XOR N) AND M equals zero, and returns that value.
  5. The VLS checks the client's value V, and then checks the signature on the message. If the signature verifies, then the VLS removes the old registration and creates a new registration based on the data in the message, completing processing of the message.
Basic lookup logic flow
  1. A vat wishing to locate another vat uses the standard VatTP startup protocol to build a connection to the VLS.
  2. After receiving the desired VatID, the VLS checks if it is registered. If it is not registered, the VLS returns TOK_NOT_ME to the connecting vat.

  3. If it is registered, the VLS returns TOK_TRY with the registered address(es) to the connecting vat. 

Off the shelf alternatives

I don't know of any off the shelf alternatives that are available.

Other Design Objectives, Constraints and Assumptions

  • The client implementation may wish to limit the time spent calculating the hash cash value to prevent denial of service attacks from a hostile VLS.

Current implementation


Startup, Shutdown, and Steady State

The object of startup is to create the objects needed for the steady state. The object of shutdown is to clean up the steady state. Because of these objectives, I will describe the steady state first.

Steady State


Startup Protocol




Which directories on our tree does this subsystem cover?


Is it JavaDoc'ed?




Testing and Debugging


Design Issues

Resolved Issues

History of issues raised and resolved during initial design, or during design inspections. Can also include alternative designs, with the reasons why they were rejected

Open Issues

  • In 1.1.3, Java appears to get the IP address of the machine once at startup. In the case of someone running Microcosm who is dropped by their ISP, they get a new IP address when they re-dial. We need to deal with this problem one way or another.
  • Sidney suggests having a way to configure the "listen" address (IP + port number) during VLS registration to handle certain proxying firewalls.
  • Does LDAP (Lightweight Directory Access Protocol) have any application to our VLS requirements.
Unless stated otherwise, all text on this page which is either unattributed or by Mark S. Miller is hereby placed in the public domain.
ERights Home elib / distrib / vattp 
Back to: SSL & Data-Pluribus No Next Sibling
Download    FAQ    API    Mail Archive    Donate

report bug (including invalid html)

Golden Key Campaign Blue Ribbon Campaign