diff --git a/i2p2www/legacy.py b/i2p2www/legacy.py index c185e8e8..685dc8c5 100644 --- a/i2p2www/legacy.py +++ b/i2p2www/legacy.py @@ -34,7 +34,7 @@ LEGACY_PAGES_MAP={ 'configuration': 'docs/spec/configuration', 'contact': 'about/contact', 'cvs': 'misc/cvs', - 'datagrams': 'docs/spec/datagrams', + 'datagrams': 'docs/api/datagrams', 'dev-guidelines': 'volunteer/guides/dev-guidelines', 'developerskeys': 'volunteer/develop/developers-keys', 'donate': 'volunteer/donate', diff --git a/i2p2www/pages/global/nav.html b/i2p2www/pages/global/nav.html index 558a9b33..b1051bb7 100644 --- a/i2p2www/pages/global/nav.html +++ b/i2p2www/pages/global/nav.html @@ -45,6 +45,7 @@
  • BOB
  • {{ _('Streaming library') }}
  • {{ _('Ministreaming library') }}
    • +
  • {{ _('Datagrams') }}
  • I2PControl
    • diff --git a/i2p2www/pages/site/docs/api/datagrams.html b/i2p2www/pages/site/docs/api/datagrams.html new file mode 100644 index 00000000..176bd237 --- /dev/null +++ b/i2p2www/pages/site/docs/api/datagrams.html @@ -0,0 +1,114 @@ +{% extends "global/layout.html" %} +{% block title %}{% trans %}Datagrams{% endtrans %}{% endblock %} +{% block lastupdated %}{% trans %}August 2010{% endtrans %}{% endblock %} +{% block accuratefor %}0.8{% endblock %} +{% block content %} +

    {% trans %}Datagram Overview{% endtrans %}

    +

    {% trans i2cp=site_url('docs/protocol/i2cp') -%} +Datagrams build upon the base I2CP to provide authenticated +and repliable messages in a standard format. This lets applications reliably read +the "from" address out of a datagram and know that the address really sent the +message. This is necessary for some applications since the base I2P message is +completely raw - it has no "from" address (unlike IP packets). In addition, the +message and sender are authenticated by signing the payload. +{%- endtrans %}

    + +

    {% trans streaming=site_url('docs/api/streaming'), +transports=site_url('docs/transport') -%} +Datagrams, like streaming library packets, +are an application-level construct. +These protocols are independent of the low-level transports; +the protocols are converted to I2NP messages by the router, and +either protocol may be carried by either transport. +{%- endtrans %}

    + +

    {% trans %}Application Guide{% endtrans %}

    +

    {% trans url='http://docs.i2p-projekt.de/javadoc/net/i2p/client/datagram/package-summary.html', +sam= site_url('docs/api/sam'), +socks=site_url('docs/api/socks') -%} +Applications written in Java may use the +datagram API, +while applications in other languages +can use SAM's datagram support. +There is also limited support in i2ptunnel in the SOCKS proxy, +the 'streamr' tunnel types, and udpTunnel classes. +{%- endtrans %}

    + +

    {% trans %}Datagram Length{% endtrans %}

    +

    {% trans -%} +The application designer should carefully consider the tradeoff of repliable vs. non-repliable +datagrams. Also, the datagram size will affect reliability, due to tunnel fragmentation into 1KB +tunnel messages. The more message fragments, the more likely that one of them will be dropped +by an intermediate hop. Messages larger than a few KB are not recommended. +{%- endtrans %}

    + +

    {% trans elgamalaes=site_url('docs/how/elgamal-aes') -%} +Also note that the various overheads added by lower layers, in particular asymmetric +ElGamal/AES, place a large burden on intermittent messages +such as used by a Kademlia-over-UDP application. The implementations are currently tuned +for frequent traffic using the streaming library. There are a high number +of session tags delivered, and a short session tag lifetime, for example. +There are currently no configuration parameters available within I2CP to tune +the ElGamal Session Tag parameters. +{%- endtrans %}

    + +

    {% trans %}I2CP Protocol Number and Ports{% endtrans %}

    +

    {% trans -%} +The standard I2CP protocol number for datagrams is 17. Applications may or may not choose to set the +protocol in the I2CP header. It is not set by default. +It must be set to demultiplex datagram and streaming traffic received on the same Destination. +{%- endtrans %}

    + +

    {% trans i2cp=site_url('docs/protocol/i2cp') -%} +As datagrams are not connection-oriented, the application may require +port numbers to correlate datagrams with particular peers or communications sessions, +as is traditional with UDP over IP. +Applications may add 'from' and 'to' ports to the I2CP (gzip) header as described in +the I2CP page. +{%- endtrans %}

    + +

    {% trans -%} +There is no method within the datagram API to specify whether it is non-repliable (raw) +or repliable. The application should be designed to expect the appropriate type. +The I2CP protocol number or port could also be used by the application to +indicate datagram type. +{%- endtrans %}

    + +

    {% trans i2psession='http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSession.html', +i2psessionmuxed='http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSessionMuxedImpl.html' -%} +The protocols and ports may be set in I2CP's +I2PSession API, +as implemented in +I2PSessionMuxedImpl. +{%- endtrans %}

    + +

    {% trans %}Data Integrity{% endtrans %}

    +

    {% trans i2cp=site_url('docs/protocol/i2cp') -%} +Data integrity is assured by the gzip CRC-32 checksum implemented in +the I2CP layer. +There is no checksum field in the datagram protocol. +{%- endtrans %}

    + +

    {% trans %}Packet Encapsulation{% endtrans %}

    +

    {% trans garlicrouting=site_url('docs/how/garlic-routing'), +i2cp=site_url('docs/protocol/i2cp'), +i2np=site_url('docs/protocol/i2np'), +tunnelmessage=site_url('docs/spec/tunnel-message') -%} +Each datagram is sent through I2P as a single message (or as an individual clove in a +Garlic Message). +Message encapsulation is implemented in the underlying +I2CP, +I2NP, and +tunnel message layers. +There is no packet delimiter mechanism or length field in the datagram protocol. +{%- endtrans %}

    + +

    {% trans %}Specification{% endtrans %}

    + +

    {% trans -%} +See the Datagrams Specification page. +{%- endtrans %}

    + + + +{% endblock %} diff --git a/i2p2www/pages/site/docs/spec/datagrams.html b/i2p2www/pages/site/docs/spec/datagrams.html index cc55da37..a64a328e 100644 --- a/i2p2www/pages/site/docs/spec/datagrams.html +++ b/i2p2www/pages/site/docs/spec/datagrams.html @@ -3,105 +3,9 @@ {% block lastupdated %}{% trans %}August 2010{% endtrans %}{% endblock %} {% block accuratefor %}0.8{% endblock %} {% block content %} -

    {% trans %}Datagram Overview{% endtrans %}

    -

    {% trans i2cp=site_url('docs/protocol/i2cp') -%} -Datagrams build upon the base I2CP to provide authenticated -and repliable messages in a standard format. This lets applications reliably read -the "from" address out of a datagram and know that the address really sent the -message. This is necessary for some applications since the base I2P message is -completely raw - it has no "from" address (unlike IP packets). In addition, the -message and sender are authenticated by signing the payload. -{%- endtrans %}

    - -

    {% trans streaming=site_url('docs/api/streaming'), -transports=site_url('docs/transport') -%} -Datagrams, like streaming library packets, -are an application-level construct. -These protocols are independent of the low-level transports; -the protocols are converted to I2NP messages by the router, and -either protocol may be carried by either transport. -{%- endtrans %}

    - -

    {% trans %}Application Guide{% endtrans %}

    -

    {% trans url='http://docs.i2p-projekt.de/javadoc/net/i2p/client/datagram/package-summary.html', -sam= site_url('docs/api/sam'), -socks=site_url('docs/api/socks') -%} -Applications written in Java may use the -datagram API, -while applications in other languages -can use SAM's datagram support. -There is also limited support in i2ptunnel in the SOCKS proxy, -the 'streamr' tunnel types, and udpTunnel classes. -{%- endtrans %}

    - -

    {% trans %}Datagram Length{% endtrans %}

    -

    {% trans -%} -The application designer should carefully consider the tradeoff of repliable vs. non-repliable -datagrams. Also, the datagram size will affect reliability, due to tunnel fragmentation into 1KB -tunnel messages. The more message fragments, the more likely that one of them will be dropped -by an intermediate hop. Messages larger than a few KB are not recommended. -{%- endtrans %}

    - -

    {% trans elgamalaes=site_url('docs/how/elgamal-aes') -%} -Also note that the various overheads added by lower layers, in particular asymmetric -ElGamal/AES, place a large burden on intermittent messages -such as used by a Kademlia-over-UDP application. The implementations are currently tuned -for frequent traffic using the streaming library. There are a high number -of session tags delivered, and a short session tag lifetime, for example. -There are currently no configuration parameters available within I2CP to tune -the ElGamal Session Tag parameters. -{%- endtrans %}

    - -

    {% trans %}I2CP Protocol Number and Ports{% endtrans %}

    -

    {% trans -%} -The standard I2CP protocol number for datagrams is 17. Applications may or may not choose to set the -protocol in the I2CP header. It is not set by default. -It must be set to demultiplex datagram and streaming traffic received on the same Destination. -{%- endtrans %}

    - -

    {% trans i2cp=site_url('docs/protocol/i2cp') -%} -As datagrams are not connection-oriented, the application may require -port numbers to correlate datagrams with particular peers or communications sessions, -as is traditional with UDP over IP. -Applications may add 'from' and 'to' ports to the I2CP (gzip) header as described in -the I2CP page. -{%- endtrans %}

    - -

    {% trans -%} -There is no method within the datagram API to specify whether it is non-repliable (raw) -or repliable. The application should be designed to expect the appropriate type. -The I2CP protocol number or port could also be used by the application to -indicate datagram type. -{%- endtrans %}

    - -

    {% trans i2psession='http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSession.html', -i2psessionmuxed='http://docs.i2p-projekt.de/javadoc/net/i2p/client/I2PSessionMuxedImpl.html' -%} -The protocols and ports may be set in I2CP's -I2PSession API, -as implemented in -I2PSessionMuxedImpl. -{%- endtrans %}

    - -

    {% trans %}Data Integrity{% endtrans %}

    -

    {% trans i2cp=site_url('docs/protocol/i2cp') -%} -Data integrity is assured by the gzip CRC-32 checksum implemented in -the I2CP layer. -There is no checksum field in the datagram protocol. -{%- endtrans %}

    - -

    {% trans %}Packet Encapsulation{% endtrans %}

    -

    {% trans garlicrouting=site_url('docs/how/garlic-routing'), -i2cp=site_url('docs/protocol/i2cp'), -i2np=site_url('docs/protocol/i2np'), -tunnelmessage=site_url('docs/spec/tunnel-message') -%} -Each datagram is sent through I2P as a single message (or as an individual clove in a -Garlic Message). -Message encapsulation is implemented in the underlying -I2CP, -I2NP, and -tunnel message layers. -There is no packet delimiter mechanism or length field in the datagram protocol. -{%- endtrans %}

    +

    {% trans -%} +See the Datagrams page for an overview of the Datagrams API. +{%- endtrans %}

    {% trans %}Specification{% endtrans %}