v6wpd Requirements Specification

   $Id: v6wpd_req_spec.txt,v 1.2 2003/01/21 15:36:24 can Exp $
    1. Introduction
         1. Purpose
            This document describes the functional requirements of the
            Whois Proxy for ipv6 clients (v6wpd). This document is
            intended for developers who will design and implement and
            test the system.
         2. Scope
            This document describes how v6wpd will operate. v6pwd is a
            gateway for clients to connect to the whois server via an
            ipv6 interface.
         3. Definitions, Acronyms and Abbrevations
            v6wpd: ipv6 whois proxy daemon.
         4. References
            Source code, along with the documentation, will reside in the
            internal CVS system of RIPE NCC.
    2. Overall Description
         1. Product Perspective
            The product is a gateway to the whois server, communicating
            queries and answers with minimal pre- and post- processing,
            like handling access lists and denying oversized data. The
            software can be perceived as the combination of a simplified
            whois server and whois client. Much of the code will be
            borrowed from these softwares.
              1. System Interfaces
                 The system should run on Solaris, FreeBSD and Linux.
              2. User Interfaces
                 The system will use the standard whois protocol,
                 therefore a ipv6 enabled whois client or the standard
                 telnet interface can be used for communicating with the
                 system.
              3. Software Interfaces
                 v6wpd will forward queries to the whois server and
                 receive answers using the standard whois protocol.
                 Standard whois client will be embedded into the
                 software.
              4. Communication Interfaces
                 v6wpd will communicate with whois server directly.
                 IPv6 Whois queries are converted to IPv4 Whois queries.
                 This way the existing IPv4 ACL mechanisms can be used.
                 The RFC1918 space is used. IPv6 addresses will get
                 mapped to the same IPv4 address on all queries, until
                 the IPv4 space used is exhausted.
              5. Operations
                       1. Starting/Stopping the System
                        1. The system must start after querying is
                           enabled on the whois server.
                        2. The system must be stopped before querying is
                           disabled on the whois server.
                        3. There must be two kinds of stopping/starting
                           the system. The first mode is
                           starting/stopping the processes so the system
                           either responds or not. In the second mode,
                           after stopping the system, it will respond
                           with a message indicating that that the v6
                           queries are not available. Starting the system
                           will resume operations.
                       2. Monitoring the System
                        1. The process must be monitored and
                           notifications should be sent in case of:
                             1. The process dies,
                             2. The process can't answer a simple query
                                in a timely manner.
         2. Product Function
            v6wpd functions are:
              1. Determining the corresponding ipv4 address of the
                 connecting ipv6 host,
              2. Verifying that the input is not larger than a specified
                 amount, and denying the connection if it exceeds the
                 limit,
              3. Verifying that the the host can issue -V switch, by
                 checking the access list, denying the connection if it
                 supplied while it cannot,
              4. Incrementing the query count of the host,
              5. Forwarding the query to the whois server, supplying the
                 designated ipv4 address in the -V switch,
              6. Forwarding answer received from the whois server to the
                 connecting host.
         3. User Characteristics
            A typical user is the causal user of the whois server, with
            the only difference being the source address of type ipv6.
         4. Constraints
            Both the input to the gateway and the query forwarded to the
            whois server must not exist a configured specified length.
         5. Assumptions and Dependencies
            Software depends on the whois protocol, so it is assumed that
            the whois server and the client uses the same protocol.
            It is assumed that the related whois server is setup so that
            the v6wpd is accepted as a proxy which can issue -V requests.
    3. Specific Requirements
         1. Configuration File Requirements
              1. Configuration variables must be stored in a seperate
                 configuration file.
              2. There must be keywords for specifying:
                   1. ipv6 address and port to listen for queries,
                   2. ipv4 address and port to forward queries,
                   3. maximum length of query to accept,
                   4. maximum length of query to forward,
                   5. maximum number of concurrent connections from a
                      unique host,
                   6. maximum number of concurrent connections,
                   7. table name to store ipv6 to ipv4 mappings,
                   8. table name to store the access list for ipv6,
                   9. ipv4 address range to map ipv6 addresses,
                  10. file name to use for logging,
                  11. related error message texts.
         2. Handling incoming IPv6 Queries
              1. Any connection request must be logged with the
                 corresponding ipv6 address.
              2. Input will be read until it either is longer than
                 maximum length of query to accept, or <CRLF> or <LF> is
                 received.
              3. -V switch can only be supplied in the beginning of the
                 query, before anything else. This requirement is
                 completely for the purpose of easier handling.
              4. If there is a -V switch in the query, the client must be
                 checked whether it is a trusted proxy. Connection must
                 be denied if it is not, logging the condition.
              5. If -V is supplied and it's accepted, the client ipv6
                 address must be extracted from the -V flag.
              6. The corresponding ipv4 address to be presented to the
                 whois server must be determined. See the related section
                 for requirements on this mapping.
              7. Last used time and the query count of the ipv6 address
                 must be updated upon every query forwarding.
              8. -V switch to forward to the whois server must be formed
                 depending on the requirements in the related section. It
                 must either be replaced with the existing -V flag or
                 embedded into the query to forward.
              9. The size of the resulting query must be checked whether
                 it is longer than the configured maximum length, and the
                 query must not be forwarded if it exceeds, with the
                 error message returned to the user.
             10. Accepted query to forward must be communicated to the
                 whois server as a standard whois client. Output must be
                 sent back to the connecting ipv6 client unaltered. The
                 query must be logged.
             11. After the output is finished, connection must be closed
                 by the server, unless -k switch is used. In that case,
                 connection must not be closed until there is a timeout
                 or explicit close from either sides.
         3. Handling ipv6 to ipv4 mapping
              1. There must be a table which holds information about
                 which ipv6 address has been mapped to which ipv4
                 address, including the time of the first mapping, the
                 time of last usage, and how many times it has been used
                 (the host has made a query).
              2. Given the ipv6 address, the system must check if the
                 address has been assigned an ipv4 address before. In
                 this case, the address must be reused, logging the
                 condition.
              3. If the ipv6 address hasn't been assigned a ipv4 address,
                 the next free ipv4 address must be assigned, updating
                 the first mapped time to current time and usage counter
                 to 0. The condition must be logged.
              4. If there are no free addresses to assign to the new ipv6
                 address, the first mapping with the earlist first mapped
                 time must be remapped to the new address. This must also
                 be logged.
         4. Forming the -V switch to forward
              1. If there are no -V switches provided by the host, a new
                 -V switch must be formed, with the format:

     -Videntifier-tag,IPv4-address
              2. If there already exists a -V flag, a new -V flag must be
                 formed, with the format:

     -Vmyidentifier-tag@v6address-of-proxy@proxy-identifier-tag@ipv6endu
     ser,IPv4-address
     where
                    # myidentifier-tag: tag for this proxy
                    # v6address-of-proxy: Ipv6 address of the connecting
                      client
                    # identifier-tag: new tag added by the current proxy.
                    # ipv6enduser: address of the end user making the
                      request.

                 The old and the new -V flag must be logged.
         5. Requirements for Controlling Resource Usage
              1. The same timeout for input termination for the whois
                 server must be used in the proxy, (currently 2 minutes).
              2. Number of simultaneous connections from a host and from
                 all hosts must be checked and connections must be
                 restricted.
              3. Maximum length of the incoming and outcoming packets
                 must be limited.
