From c024398b939fe7a682ade32c2a328df17c0f58a3 Mon Sep 17 00:00:00 2001 From: zzz <zzz@mail.i2p> Date: Sun, 9 Nov 2008 15:54:04 +0000 Subject: [PATCH] Add some javadoc files --- core/java/src/net/i2p/data/i2cp/package.html | 49 +++++++ core/java/src/net/i2p/data/package.html | 6 + core/java/src/net/i2p/stat/package.html | 7 + core/java/src/net/i2p/util/package.html | 6 + .../java/src/net/i2p/data/i2np/package.html | 129 ++++++++++++++++++ .../net/i2p/router/transport/tcp/package.html | 5 +- 6 files changed, 201 insertions(+), 1 deletion(-) create mode 100644 core/java/src/net/i2p/data/i2cp/package.html create mode 100644 core/java/src/net/i2p/data/package.html create mode 100644 core/java/src/net/i2p/stat/package.html create mode 100644 core/java/src/net/i2p/util/package.html create mode 100644 router/java/src/net/i2p/data/i2np/package.html diff --git a/core/java/src/net/i2p/data/i2cp/package.html b/core/java/src/net/i2p/data/i2cp/package.html new file mode 100644 index 0000000000..0d9bbda5c4 --- /dev/null +++ b/core/java/src/net/i2p/data/i2cp/package.html @@ -0,0 +1,49 @@ +<html><body> +<p> +The Invisible Internet Client Protocol (I2CP) allows applications simplified access to +the I2P network without requiring them to deal with the issues involved with the +Invisible Internet Network Protocol (I2NP). Specifically, it defines the wire level +protocol as well as semantics for the messages passed between clients and the router +for communicating with the router over bidirectional TCP/IP sockets. I2CP does not +specify how the client libraries are created, what APIs they expose to applications, or +even what language they're written in. +</p> +<h2>Requirements</h2> +<p> +I2CP requires that the client can access the router over bidirectional TCP sockets. In +nearly all cases, these connections will be over to the local machine. +</p> +<h2>Threat Model</h2> +<p> +I2CP does not provide data confidentiality or handle lossy connections beyond what +TCP has built in. For this reason, I2CP really should only be run between clients and +routers on the same machine or over trusted networks. Secured I2CP transports may +be added in the future. I2CP however does not expose any private keys across the +wire - proof of authorization to collect messages for a Destination is provided by +public key signatures. +</p> +<h1>Messages</h1> +<p> +These classes are the currently defined messages in the Invisible Internet Client +Protocol (I2CP), though common data structures are located in the I2P Common Data +Structure Specification. For simplicity, all I2CP messages begin with the same +structure, though that structure is not listed below. Specifically, all I2CP messages +transmitted begin with a 4 byte Integer specifying the entire size of the current +message's body (the body being what's specified below), followed by a 1 byte +Integer specifying the type of message (the id field below), after which the rest of +the message is formatted according to the type of message, as specified below. +</p><p> +If there is a fatal error causing either the client or the router to desire to cancel sending +a message part way through, it should drop its connection. Administrative sessions are +not stateful (aka each administrative message from client to router must provide +authentication), but normal client sessions are stateful and survive disconnects. Client +sessions expire when either the client sends a DestroySessionMessage or the router +times out the session according to its own configurable timer. If a client sends any +message other than a CreateSessionMessage when there is no valid session, the +router must reply with a SessionStatusMessage specifying that the session is not +valid. +</p><p> +Note: the contents and bitbuckets for specific DataStructures are detailed in the +I2P Data Structures Spec. +</p> +</body></html> diff --git a/core/java/src/net/i2p/data/package.html b/core/java/src/net/i2p/data/package.html new file mode 100644 index 0000000000..5b9be2f54c --- /dev/null +++ b/core/java/src/net/i2p/data/package.html @@ -0,0 +1,6 @@ +<html><body> +<p> +These classes define the common data structures used by the various +I2P protocols. +</p> +</body></html> diff --git a/core/java/src/net/i2p/stat/package.html b/core/java/src/net/i2p/stat/package.html new file mode 100644 index 0000000000..745e9d0014 --- /dev/null +++ b/core/java/src/net/i2p/stat/package.html @@ -0,0 +1,7 @@ +<html><body> +<p> +These classes define the statistics package used extensively throughout +the I2P router - both for adaptive operation of the router +and for debugging. +</p> +</body></html> diff --git a/core/java/src/net/i2p/util/package.html b/core/java/src/net/i2p/util/package.html new file mode 100644 index 0000000000..3c08401d2f --- /dev/null +++ b/core/java/src/net/i2p/util/package.html @@ -0,0 +1,6 @@ +<html><body> +<p> +These classes define the several useful utilities used +throughout the router and applications. +</p> +</body></html> diff --git a/router/java/src/net/i2p/data/i2np/package.html b/router/java/src/net/i2p/data/i2np/package.html new file mode 100644 index 0000000000..666c5bf224 --- /dev/null +++ b/router/java/src/net/i2p/data/i2np/package.html @@ -0,0 +1,129 @@ +<html><body> +<p> +The Invisible Internet Network Protocol (I2NP) is only a part of how an +application can send messages over the network. The Invisible Internet Client +Protocol (I2CP) defines how client applications written in any language can +communicate with the network routers. In addition, various transport protocols define +the specifics of how data is passed from one router to another over the network. I2NP +does not specify or require any particular transport layer, allowing transport protocols +to work over TCP, Polling HTTP, SMTP+POP3/IMAP, UDP, among anything else +that can pass data. I2NP merely requires that they: +<ul> +<li> +Register a unique identifier for use in RouterAddress structures consisting of no +more than 32 UTF-8 characters. +<li> +Define standard text based options that uniquely define a contact method (for +example .hostname. and .port. or .email address.) as usable in the +RouterAddress structure's set of options. +<li> +Provide a means to reliably deliver a chunk of data, where the contents of any +particular chunk is delivered in order. However, different chunks of data do not +need to be delivered in order. +<li> +Secure the chunks of data from alteration or disclosure (e.g. encrypt them and use +checksums). +<li> +Enable the router to control the transport's bandwidth usage. +<li> +Provide estimates for the latency and bandwidth associated with passing a chunk of +data. +<li> +Provide a programmable interface suitable for integration with various routers. +</ul> +</p> +<p> +Transports themselves can implement advanced features, such as steganography, +constant rate delivery, dummy message delivery, and may even run on top of existing +networks, such as mixminion, kazaa, gnunet, and freenet. Transports can even be +written to run over I2P itself, accessing it as a client and mixing the message through +other routers. +</p> +<p> +Sandwiched between I2CP and the various I2P transport protocols, I2NP manages the +routing and mixing of messages between routers, as well as the selection of what +</p> +<h2>Destination Sends a Message</h2> +<p> +Following is a common usage for I2NP Messages. +For other usages, including tunnel building, see the I2NP specification +or the tunnel build document. +</p> +<p> +Whenever a Destination wants to send a message to to another Destination, it +provides its local router with both the Destination structure and the raw bytes of the +message to be sent. The router then determines where to send it, delivers it through +outbound tunnels, instructing the end point to pass it along to the appropriate inbound +tunnel, where it is passed along again to that tunnel's end point and made available to +the target for reception. To understand fully, each step in the process must be +explained in detail. +<ul> +<li> +First, once the originating router receives the message and the Destination, it +attempts to find the LeaseSet associated with it as stored in the Network Database +under the key calculated by SHA256 of the Destination. +<li> +The router then builds a GarlicMessage addressed to the SHA256 of the +PublicKey from the LeaseSet with the real data to be delivered. This +GarlicMessage contains at least one GarlicClove in which there are instructions to +deliver the clove's payload to the Destination. Additional cloves may be present, +and in fact, if the source router desires guaranteed delivery, it will include a clove +requesting source route delivery of a DeliveryStatusMessage back to itself. The +body of the GarlicMessage with all enclosed GarlicCloves is encrypted to the key +specified on the LeaseSet using the ElGamal+AES256 algorithm described in the +data structure spec. +<li> +The router then selects one or more outbound tunnels through which the +GarlicMessage will be delivered. +<li> +Then the router selects one or more of those Lease structures from the LeaseSet +and constructs a TunnelMessage along with DeliveryInstructions for the +outbound tunnel's end point to deliver the GarlicMessage to the inbound tunnel's +gateway router. +<li> +The source router then passes the various TunnelMessages down the outbound +tunnel to that tunnel's end point, where the instructions are decrypted, specifying +where the message should be delivered. +<li> +At this point, the end point must determine how to contact the router specified in +the decrypted DeliveryInstructions, perhaps looking up RouterInfo or +LeaseSet structures in the Network Database, and maybe even delaying a +requested period of time before passing on the message. +<li> +Once the tunnel end point has the data it needs to contact the inbound tunnel's +gateway router, it then attempts to contact it either directly through one of its public +RouterAddress or source routed through one of its published trusted peers. Over +this medium the tunnel end point delivers the GarlicMessage as it was wrapped by +the source router, along with the TunnelId. +<li> +Once delivered to the inbound tunnel's gateway, the gateway builds a +TunnelMessage wrapping the GarlicMessage, encrypting a +DeliveryInstructions to specify local delivery upon arrival at the tunnel's end +point. +<li> +Once the TunnelMessage is passed down to the end point in inbound tunnel, the +router opens the DeliveryInstructions, notes the request to deliver it locally, +and then proceeds to review the contents of the TunnelMessage's payload, which in +this case is a GarlicMessage addressed to the SHA256 of a LeaseSet that it has +published. It then decrypts the payload of the message with ElGamal + AES256. +<li> +After opening up the GarlicMessage, it reviews each of the GarlicCloves and +processes them each. Cloves with DeliveryInstructions addressed to a local +Destination are delivered to the associated client application, other cloves asking +for local processing (e.g. Network Database messages or DeliveryStatusMessages) +are processed, and cloves asking for forwarding to other routers are passed off for +delivery. +</ul> +<p> +There are several important points of note in this scenario. First, the source router +determines how many messages to send, how many outbound tunnels to send them +out, how many inbound tunnels to send them to, and how many cloves should include +DeliveryStatusMessage responses. The algorithm deciding these choices depends +both on the router implementation as well as the Destination's session configuration +options specified to balance the bandwidth, latency, reliability, and anonymity +constraints. Also, instead of using outbound tunnels to get the message to the inbound +tunnel's gateway, the router may decide to source router the message instead. If the +message id for a clove has already been processed or its expiration has passed, the +clove is dropped. +</p> +</body></html> diff --git a/router/java/src/net/i2p/router/transport/tcp/package.html b/router/java/src/net/i2p/router/transport/tcp/package.html index 7df3c1952f..c236f03a37 100644 --- a/router/java/src/net/i2p/router/transport/tcp/package.html +++ b/router/java/src/net/i2p/router/transport/tcp/package.html @@ -1,5 +1,8 @@ <html><body> -<p>Implements the transport for communicating with other routers via TCP/IP.</p> +<p> +OBSOLETE - see NTCP. +Implements the transport for communicating with other routers via TCP/IP. +</p> <h1>Connection protocol</h1> -- GitLab