Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#716 closed defect (fixed)

I2p doc inaccuracies

Reported by: Eridani Owned by: zzz
Priority: minor Milestone:
Component: www/i2p Version: 0.9.1
Keywords: docs test Cc: zab@…
Parent Tickets:

Description

Sorry for not doing this sooner, but here are a few inaccuracies in the SSU docs, mostly at www.i2i2.de/udp_spec.html. I'll look over other parts later to find other issues.

First, while it is correctly mentioned in the warning at the bottom of www.i2p2.de/how_cryptography.html, the main udp pages make no mention that the hmac used is non standard, nor is the how_Cryptography page linked when talking about hmac.

A second issue regarding the hmac, the docs incorrectly state that the macKey is the session key, when in fact the session key is the first 32 bytes from DH, while the mac key is the second 32 bytes. A third issue then pops up, due to a quirk in java's bignum, which when converted into a byte array, will perpend a null byte if the very first bit is 1. This one was an absolute joy to discover...

In a different part, PeerTest? messages sent as Alice replace the ipsize, ip, and port fields with a string of three null bytes. The java code comments correctly mention this, while the online docs do not.

Some other things, while not incorrect, are not sufficiently explained, such as ACKs and ACK bitfields which have minimal description. The udp docs also fail to mention router behavior, such as resending messages, and the i2np message sent after an SSU session is created.

Other areas of the docs seemed more accurate, but could use more detail and clarity. I'll add other suggestions later.

Subtickets

Change History (8)

comment:1 Changed 7 years ago by zab

  • Cc zab@… added

comment:2 follow-up: Changed 7 years ago by zzz

  • Milestone set to 0.9.3
  • Owner set to zzz
  • Status changed from new to accepted

Thanks. I'll fix up the SSU stuff. No idea what you are doing (reimplmenting SSU in Java?) but BigInteger? has nothing to do with the SSU spec.

If you find doc issues outside of SSU please open a separate ticket.

comment:3 Changed 7 years ago by zzz

I think I've fixed and pushed everything except the macKey/sessionKey issue, which I haven't had time to research yet. Please take a look.

comment:4 in reply to: ↑ 2 Changed 7 years ago by killyourtv

Replying to zzz:

No idea what you are doing (reimplmenting SSU in Java?) but BigInteger? has nothing to do with the SSU spec.

Python.

comment:5 Changed 7 years ago by str4d

  • Keywords docs added

comment:6 Changed 6 years ago by str4d

  • Keywords test added
  • Milestone 0.9.3 deleted

comment:7 Changed 6 years ago by zzz

  • Resolution set to fixed
  • Status changed from accepted to closed

Fixed in 948a4bafaaa9996bae309c0f4fbde7db70e666a3 , please review.

Now I understand what you meant about the Java BigInteger? issue and why it affects the spec.

Also discovered that the code completely blows up for (minimized) DH key lengths between 32 and 63 bytes, not that that could ever happen in a zillion years since the nominal key length is 256 bytes. So the docs now have a big TBD for that. I'll probably open a new ticket on it.

If you have any other doc errors or suggestions please open a new ticket.

comment:8 Changed 6 years ago by zzz

#963 created for the short-key issue

Note: See TracTickets for help on using tickets.