diff --git a/i2p2www/formatters.py b/i2p2www/formatters.py index fd8006d5..2f03f5b5 100644 --- a/i2p2www/formatters.py +++ b/i2p2www/formatters.py @@ -37,6 +37,7 @@ _escape_html_table = { kinds = { 't': 'type', 's': 'struct', + 'm': 'msg', } def escape_html(text, table=_escape_html_table): @@ -715,6 +716,10 @@ class I2PHtmlFormatter(Formatter): if tagsfile and ttype in Token.Name.Class: filename, kind = self._lookup_ctag(value) + # Handle message types + if not kind and value.endswith('Message'): + value = value[:-7] + filename, kind = self._lookup_ctag(value) if kind: base, filename = os.path.split(filename) if base: diff --git a/i2p2www/lexers.py b/i2p2www/lexers.py index e369a0d4..9e1220fb 100644 --- a/i2p2www/lexers.py +++ b/i2p2www/lexers.py @@ -12,14 +12,16 @@ class DataSpecLexer(RegexLexer): (r'(\s+)([\+|])', bygroups(Text, Text), 'content'), (r'(\s*)(~)', bygroups(Text, Generic.Strong), 'content'), (r'(\s*)([\w=;]+)(\s[\w=;]+)*(\s)(::)(\s)', bygroups(Text, Name.Tag, Name.Tag, Text, Operator, Text)), - (r'(\s*)`((?:[A-Z][a-z]+)(?:[A-Z][a-z]*)*)`', bygroups(Text, Name.Class)), + (r'(\s*)`((?:[A-Z][a-z0-9]+)(?:[A-Z][a-z0-9]*)*)(\.)(.*)`', bygroups(Text, Name.Class, Operator, Name.Tag)), + (r'(\s*)`((?:[A-Z][a-z0-9]+)(?:[A-Z][a-z0-9]*)*)`', bygroups(Text, Name.Class)), (r'(\s*)([A-Z]{2,})', bygroups(Text, Name.Constant)), (r'(\s*)([\[\]])', bygroups(Text, Punctuation)), (r'(\s*)(\$\w+)', bygroups(Text, Name.Tag)), + (r'(\s*)(0x[0-9a-f]+)', bygroups(Text, Number.Hex)), (r'(\s*)([0-9]+)(\+)?', bygroups(Text, Number, Punctuation)), (r'(-)([0-9]+)', bygroups(Punctuation, Number)), - (r'(\s*)(->|<=|>=|\*)', bygroups(Text, Operator)), - (r'(\s*)([\w()-=\'<>]+)', bygroups(Text, Comment)), + (r'(\s*)(->|<=|>=|\*|\^)', bygroups(Text, Operator)), + (r'(\s*)([\w()-=\'<>?]+)', bygroups(Text, Comment)), ], 'boundary': [ (r'-{3,}\+$', Text, '#pop'), diff --git a/i2p2www/pages/site/docs/api/i2pcontrol.html b/i2p2www/pages/site/docs/api/i2pcontrol.html index a45e0f3b..7b3ae3df 100644 --- a/i2p2www/pages/site/docs/api/i2pcontrol.html +++ b/i2p2www/pages/site/docs/api/i2pcontrol.html @@ -16,12 +16,30 @@ Parameters are only provided in a named way (maps). {%- endtrans %}
{{ _('Request:') }} -{"id":"id", "method":"Method-name","params":{"Param-key-1":"param-value-1", "Param-key-2":"param-value-2", "Token":"**actual token**"}, "jsonrpc":"2.0"} +{% highlight lang='json' %} +{ + "id": "id", + "method": "Method-name", + "params": { + "Param-key-1": "param-value-1", + "Param-key-2": "param-value-2", + "Token": "**actual token**" + }, + "jsonrpc": "2.0" +} +{% endhighlight %} {{ _('Response:') }} -{"id":"id","result":{"Result-key-1":"result-value-1","Result-key-2":"result-value-2"},"jsonrpc":"2.0"} -
{% trans commonstructures=site_url('docs/spec/common-structures'),
elgamalaes=site_url('docs/how/elgamal-aes'),
i2cp=site_url('docs/protocol/i2cp'),
-i2npspec=site_url('docs/spec/i2np'),
-tunnelmessage=site_url('docs/spec/tunnel-message') -%}
+i2npspec=site_url('docs/spec/i2np') -%}
At the layer above tunnels, I2P delivers end-to-end messages between
Destinations.
Just as within a single tunnel, we use
@@ -163,7 +162,7 @@ Each client message as delivered to the router through the
I2CP interface becomes a single
Garlic Clove
with its own
-Delivery Instructions,
+Delivery Instructions,
inside a
Garlic Message.
Delivery Instructions may specify a Destination, Router, or Tunnel.
@@ -177,12 +176,11 @@ cloves in the Garlic Message:
{% trans -%} Defines an identifier that is unique to each router in a tunnel. @@ -1010,9 +1010,9 @@ for standard options that are expected to be present in all router infos.
{% trans tunnelmessage=site_url('docs/spec/tunnel-message') -%} -Tunnel Message Delivery Instructions are defined in the Tunnel Message Specification. +Tunnel Message Delivery Instructions are defined in the Tunnel Message Specification. {% endtrans %}
{% trans i2npmessage=site_url('docs/spec/i2np') -%} -Garlic Message Delivery Instructions are defined in the I2NP Message Specification. +Garlic Message Delivery Instructions are defined in the I2NP Message Specification. {% endtrans %}
{% endblock %} diff --git a/i2p2www/pages/site/docs/spec/datagrams.html b/i2p2www/pages/site/docs/spec/datagrams.html index 9257a898..93c5d63c 100644 --- a/i2p2www/pages/site/docs/spec/datagrams.html +++ b/i2p2www/pages/site/docs/spec/datagrams.html @@ -42,7 +42,7 @@ currently limit messages to about 32 KB, although this may be raised in the futu Repliable datagrams contain a 'from' address and a signature. These add at least 427 bytes of overhead. {%- endtrans %}+{% highlight lang='dataspec' %} +----+----+----+----+----+----+----+----+ | from | + + @@ -68,27 +68,24 @@ Repliable datagrams contain a 'from' address and a signature. These add at least +----+----+----+----// - -from :: a Destination +from :: a `Destination` length: 387+ bytes The originator and signer of the datagram -signature :: a Signature - Signature type must match the signing public key type in the 'from' Destination. +signature :: a `Signature` + Signature type must match the signing public key type of $from length: 40+ bytes, as implied by the Signature type. For the default DSA_SHA1 key type: - The DSA signature of the SHA-256 hash of the payload. + The DSA `Signature` of the SHA-256 hash of the payload. For other key types: - The signature of the payload. - The signature may be verified by the signing public key of the 'from' Destination. + The `Signature` of the payload. + The signature may be verified by the signing public key of $from payload :: The data Length: 0 to ~31.5 KB (see notes) Total length: Payload length + 427+ - - -+{% endhighlight %}
Common header to all I2CP messages, containing the message length and message type. diff --git a/i2p2www/pages/site/docs/spec/i2np.html b/i2p2www/pages/site/docs/spec/i2np.html index 3dd52bc2..f335a11f 100644 --- a/i2p2www/pages/site/docs/spec/i2np.html +++ b/i2p2www/pages/site/docs/spec/i2np.html @@ -90,7 +90,7 @@ see the NTCP and SSU transport documentation for details. The following structures are elements of multiple I2NP messages. They are not complete messages. -
Common header to all I2NP messages, which contains important information like a checksum, expiration date, etc. @@ -122,7 +122,7 @@ Short (SSU, 5 bytes): {% endhighlight %}
+{% highlight lang='dataspec' %} type :: `Integer` length -> 1 byte @@ -155,11 +155,11 @@ chks :: `Integer` purpose -> checksum of the payload SHA256 hash truncated to the first byte -data :: Data +data :: length -> $size bytes purpose -> actual message contents -+{% endhighlight %}
+{% highlight lang='dataspec' %} unencrypted: receive_tunnel :: `TunnelId` length -> 4 bytes + our_ident :: `Hash` length -> 32 bytes @@ -335,7 +336,7 @@ encrypted_data :: ElGamal and AES encrypted data total length: 528 -+{% endhighlight %}
+{% highlight lang='dataspec' %} unencrypted: bytes 0-31 : SHA-256 Hash of bytes 32-527 bytes 32-526 : random data byte 527 : reply encrypted: -bytes 0-527: AES-encrypted record(note: same size as BuildRequestRecord) +bytes 0-527: AES-encrypted record (note: same size as `BuildRequestRecord`) total length: 528 -+{% endhighlight %}
+{% highlight lang='dataspec' %} unencrypted: Delivery Instructions :: as defined below Length varies but is typically 1, 33, or 37 bytes @@ -424,7 +425,7 @@ Expiration :: `Date` (8 bytes) Certificate :: Always NULL in the current implementation (3 bytes total, all zeroes) -+{% endhighlight %}
This specification is for Delivery Instructions inside Garlic Cloves only. @@ -458,7 +459,7 @@ Note that "Delivery Instructions" are also used inside Tunnel Messages, where the format is significantly different. See the -Tunnel Message documentation +Tunnel Message documentation for details. Do NOT use the following specification for Tunnel Message Delivery Instructions! @@ -488,8 +489,8 @@ Do NOT use the following specification for Tunnel Message Delivery Instructions! {% endhighlight %}
-flag: +{% highlight lang='dataspec' %} +flag :: 1 byte Bit order: 76543210 bit 7: encrypted? Unimplemented, always 0 @@ -500,33 +501,33 @@ flag: If 1, four delay bytes are included bits 3-0: reserved, set to 0 for compatibility with future uses -Session Key: +Session Key :: 32 bytes - Optional, present encrypt flag bit is set. Unimplemented, never set, never present. + Optional, present if encrypt flag bit is set. Unimplemented, never set, never present. -To Hash: +To Hash :: 32 bytes Optional, present if delivery type is DESTINATION, ROUTER, or TUNNEL If DESTINATION, the SHA256 Hash of the destination If ROUTER, the SHA256 Hash of the router If TUNNEL, the SHA256 Hash of the gateway router -Tunnel ID: +Tunnel ID :: `TunnelId` 4 bytes Optional, present if delivery type is TUNNEL The destination tunnel ID -Delay: +Delay :: `Integer` 4 bytes Optional, present if delay included flag is set - Not fully implemented. A 4 byte integer specifying the delay in seconds. + Not fully implemented. Specifies the delay in seconds. Total length: Typical length is: 1 byte for LOCAL delivery; 33 bytes for ROUTER / DESTINATION delivery; 37 bytes for TUNNEL delivery -+{% endhighlight %} @@ -606,9 +607,9 @@ with reply token: + + | | +----+----+----+----+----+----+----+----+ -|type| reply token | reply tunnel- +|type| reply token |reply_tunnelId +----+----+----+----+----+----+----+----+ - Id | SHA256 of the gateway RouterInfo | + | SHA256 of the gateway RouterInfo | +----+ + | | + + @@ -633,12 +634,12 @@ with reply token == 0: +----+----+----+----+----+-// {% endhighlight %}
-key: +{% highlight lang='dataspec' %} +key :: 32 bytes SHA256 hash -type: +type :: 1 byte type identifier bit 0: @@ -648,32 +649,32 @@ type: Through release 0.9.17, must be 0 As of release 0.9.18, ignored, reserved for future options, set to 0 for compatibility -reply token: +reply token :: 4 bytes - If greater than zero, a Delivery Status Message + If greater than zero, a Delivery Status Message is requested with the Message ID set to the value of the Reply Token. A floodfill router is also expected to flood the data to the closest floodfill peers if the token is greater than zero. -reply tunnelId: - 4 byte `TunnelID` +reply_tunnelId :: + 4 byte `TunnelId` Only included if reply token > 0 - This is the tunnel ID of the inbound gateway of the tunnel the response should be sent to - If the tunnelId is zero, the reply is sent directy to the reply gateway router. + This is the `TunnelId` of the inbound gateway of the tunnel the response should be sent to + If $reply_tunnelId is zero, the reply is sent directy to the reply gateway router. -reply gateway: +reply gateway :: 32 bytes Hash of the routerInfo entry to reach the gateway Only included if reply token > 0 - If the tunnelId is nonzero, this is the router hash of the inbound gateway + If $reply_tunnelId is nonzero, this is the router hash of the inbound gateway of the tunnel the response should be sent to. - If the tunnelId is zero, this is the router hash the response should be sent to. + If $reply_tunnelId is zero, this is the router hash the response should be sent to. -data: - If type == 0, data is a 2-byte integer specifying the number of bytes that follow, +data :: + If type == 0, data is a 2-byte `Integer` specifying the number of bytes that follow, followed by a gzip-compressed `RouterInfo`. If type == 1, data is an uncompressed `LeaseSet`. -+{% endhighlight %}
+{% highlight lang='dataspec' %} key :: 32 bytes SHA256 hash of the object to lookup @@ -772,10 +773,10 @@ flags :: through release 0.9.5, must be set to 00 as of release 0.9.6, ignored as of release 0.9.16: - 00 => normal lookup, return RI or LS or DSRM - 01 => LS lookup, return LS or DSRM - 10 => RI lookup, return RI or DSRM - 11 => exploration lookup, return DSRM containing non-floodfill routers only + 00 => normal lookup, return RI or LS or `DatabaseSearchReplyMessage` + 01 => LS lookup, return LS or `DatabaseSearchReplyMessage` + 10 => RI lookup, return RI or `DatabaseSearchReplyMessage` + 11 => exploration lookup, return `DatabaseSearchReplyMessage` containing non-floodfill routers only (replaces an excludedPeer of all zeroes) bits 7-4: through release 0.9.5, must be set to 0 @@ -789,14 +790,14 @@ reply_tunnelId :: size :: 2 byte `Integer` valid range: 0-512 - number of peers to exclude from the DatabaseSearchReply Message + number of peers to exclude from the `DatabaseSearchReplyMessage` excludedPeers :: $size SHA256 hashes of 32 bytes each (total $size*32 bytes) if the lookup fails, these peers are requested to be excluded from the list in - the DatabaseSearchReply Message. + the `DatabaseSearchReplyMessage`. if excludedPeers includes a hash of all zeroes, the request is exploratory, and - the DatabaseSearchReply Message is requested to list non-floodfill routers only. + the `DatabaseSearchReplyMessage` is requested to list non-floodfill routers only. reply_key :: 32 byte `SessionKey` @@ -812,7 +813,7 @@ reply_tags :: one or more 32 byte `SessionTags` (typically one) only included if encryptionFlag == 1, only as of release 0.9.7 -+{% endhighlight %}
+{% highlight lang='dataspec' %} key :: 32 bytes SHA256 of the object being searched @@ -886,14 +883,14 @@ num :: 1 byte `Integer` number of peer hashes that follow, 0-255 -peer_hash ($num entries) :: - 32 bytes +peer_hashes :: + $num SHA256 hashes of 32 bytes each (total $num*32 bytes) SHA256 of the `RouterIdentity` that the other router thinks is close to the key from :: 32 bytes SHA256 of the `RouterInfo` of the router this reply was sent from -+{% endhighlight %}
-msg_id :: +{% highlight lang='dataspec' %} +msg_id :: `Integer` 4 bytes - unique ID of the message we deliver the DeliveryStatus for (see common I2NP header for details) + unique ID of the message we deliver the DeliveryStatus for (see `I2NPMessageHeader` for details) -time_stamp :: Date +time_stamp :: `Date` 8 bytes time the message was successfully created or delivered -+{% endhighlight %}
+{% highlight lang='dataspec' %} Encrypted: length :: - 4 byte Integer + 4 byte `Integer` number of bytes that follow 0 - 64 KB data :: @@ -1005,7 +1002,7 @@ data :: Unencrypted data: num :: - 1 byte Integer number of `GarlicCloves` to follow + 1 byte `Integer` number of `GarlicClove`s to follow clove :: a `GarlicClove` @@ -1015,7 +1012,7 @@ Message_ID :: 4 byte `Integer` Expiration :: `Date` (8 bytes) -+{% endhighlight %}
+{% highlight lang='dataspec' %} tunnelId :: - 4 byte `TunnelID` + 4 byte `TunnelId` identifies the tunnel this message is directed at data :: 1024 bytes payload data.. fixed to 1024 bytes -+{% endhighlight %}
+{% highlight lang='dataspec' %} tunnelId :: - 4 byte `TunnelID` + 4 byte `TunnelId` identifies the tunnel this message is directed at length :: @@ -1109,7 +1106,7 @@ length :: data :: $length bytes actual payload of this message -+{% endhighlight %}
+{% highlight lang='dataspec' %} length :: 4 bytes length of the payload @@ -1142,7 +1139,7 @@ length :: data :: $length bytes actual payload of this message -+{% endhighlight %}
-Just 8 `BuildRequestRecords` attached together +{% highlight lang='dataspec' %} +Just 8 `BuildRequestRecord`s attached together record size: 528 bytes total size: 8*528 = 4224 bytes -+{% endhighlight %}
-Same format as TunnelBuildMessage, except for the addition of an "num" field in front -and $num number of Build Request Records instead of 8 +{% highlight lang='dataspec' %} +Same format as `TunnelBuildMessage`, except for the addition of a $num field in front +and $num number of `BuildRequestRecord`s instead of 8 num :: 1 byte `Integer` Valid values: 1-8 record size: 528 bytes -total size: 1 + $num*528 -+total size: 1+$num*528 +{% endhighlight %}
-Tunnel ID :: +{% highlight lang='dataspec' %} +Tunnel ID :: `TunnelId` 4 bytes the ID of the next hop @@ -133,10 +133,9 @@ Zero :: 1 byte the value 0x00 -Delivery Instructions :: +Delivery Instructions :: `TunnelMessageDeliveryInstructions` length varies but is typically 7, 39, 43, or 47 bytes Indicates the fragment and the routing for the fragment - See below for specification Message Fragment :: 1 to 996 bytes, actual maximum depends on delivery instruction size @@ -144,7 +143,7 @@ Message Fragment :: total size: 1028 Bytes -+{% endhighlight %}
The instructions are encoded with a single control byte, followed by any necessary additional information. The first bit (MSB) in that control byte determines @@ -171,7 +170,7 @@ Note that "Delivery Instructions" are also used inside Garlic Cloves, where the format is significantly different. See the -I2NP documentation +I2NP documentation for details. Do NOT use the following specification for Garlic Clove Delivery Instructions! @@ -196,8 +195,8 @@ or a complete (unfragmented) I2NP message, and the instructions are:
{% endhighlight %}-flag: +{% highlight lang='dataspec' %} +flag :: 1 byte Bit order: 76543210 bit 7: 0 to specify an initial fragment or an unfragmented message @@ -212,39 +211,39 @@ flag: If 1, extended options are included bits 1-0: reserved, set to 0 for compatibility with future uses -Tunnel ID: +Tunnel ID :: `TunnelId` 4 bytes Optional, present if delivery type is TUNNEL The destination tunnel ID -To Hash: +To Hash :: 32 bytes Optional, present if delivery type is DESTINATION, ROUTER, or TUNNEL If DESTINATION, the SHA256 Hash of the destination If ROUTER, the SHA256 Hash of the router If TUNNEL, the SHA256 Hash of the gateway router -Delay: +Delay :: 1 byte Optional, present if delay included flag is set In tunnel messages: Unimplemented, never present; original specification: bit 7: type (0 = strict, 1 = randomized) bits 6-0: delay exponent (2^value minutes) -Message ID: +Message ID :: 4 bytes Optional, present if this message is the first of 2 or more fragments (i.e. if the fragmented bit is 1) An ID that uniquely identifies all fragments as belonging to a single message - (the current implementation uses the I2NP Message ID) + (the current implementation uses `I2NPMessageHeader.msg_id`) -Extended Options: +Extended Options :: 2 or more bytes Optional, present if extend options flag is set Unimplemented, never present; original specification: One byte length and then that many bytes -size: +size :: 2 bytes The length of the fragment that follows Valid values: 1 to approx. 960 in a tunnel message @@ -254,7 +253,7 @@ Total length: Typical length is: 35 bytes for ROUTER / DESTINATION delivery or 39 bytes for TUNNEL delivery (unfragmented tunnel message); 39 bytes for ROUTER delivery or 43 bytes for TUNNEL delivery (first fragment) -+{% endhighlight %}
If the MSB of the first byte is 1, this is a follow-on fragment, and the instructions are:
@@ -265,7 +264,7 @@ Total length: Typical length is: {% endhighlight %}+{% highlight lang='dataspec' %} frag :: 1 byte Bit order: 76543210 @@ -286,7 +285,7 @@ size :: valid values: 1 to 996 total length: 7 bytes -+{% endhighlight %}