Opened 5 years ago

Last modified 5 years ago

#1147 accepted defect

Doc issues from orignal/i2pd

Reported by: zzz Owned by: zzz
Priority: maintenance Milestone:
Component: www/i2p Version: 0.9.9
Keywords: docs Cc:
Parent Tickets:

Description

ref: http://habrahabr.ru/post/205320/ (RU)

tunnel specs:

  • Top tunnels section, last couple sentences, we say OB tunnels are req'd but you can send to IBGW directly
  • Starting at 4th comment, Says we use ECB but don't explicitly say it.
  • Double encryption of IV not explained (I think it's in the background docs and old emails, perhaps could be copied over)

Other things on that page appear to be good clarifications of our docs but it may take a native RU speaker to convert it to English patches for our pages.

Anything else?

<orignal> honesly there are too many things are unclear in the docs

... but he didn't elaborate. Need specifics. Hopefully orignal will append here.

Subtickets (add)

Change History (16)

comment:1 Changed 5 years ago by orignal

https://geti2p.net/en/docs/spec/tunnel-message#delivery is not correct.
It says format of Delivery Instructions should be same for tunnel message and garlic cloves, however it's not true. Positions of TunnelID and Hash fields are inverted in case of Garlic clove.
The page refers to garlic clove documentation page, but that page refers back for delivery instruction.

comment:2 Changed 5 years ago by orignal

https://geti2p.net/en/docs/spec/tunnel-message

"Checksum ::

4 bytes
the first 4 bytes of the SHA256 hash of the contents of the message after the zero byte concatenated with the IV"

Incorrect. This hash doesn't include padding following right after zero byte.

comment:3 Changed 5 years ago by orignal

https://geti2p.net/en/docs/transport/ntcp
Nothing mentioned that first bit of first byte can't be set, in this case leading 0x00 must be added and actual key length becomes 31 bytes, due the fact Java doesn't support unsigned integers.
However this mentioned at SSU page, but NTCP and SSU are quite independent protocols.

comment:4 Changed 5 years ago by zzz

re: comment 3, the first bit of which byte?

comment:5 follow-up: Changed 5 years ago by zzz

re: comment 2, the padding is before the zero byte. There is no padding after the zero byte. So I think the doc is correct. Would you please confirm? Any suggestions on how to word it better?

Note that I fixed the checksum information on Dec. 13 2013 after orion told me it was wrong. In that checkin I added the following note:

  • The checksum does NOT cover the padding or the zero byte.

Perhaps you encountered the bad documentation before I fixed it?

comment:6 Changed 5 years ago by zzz

re: comment 1, it says:

Note that Delivery Instructions are also used inside Garlic Cloves, where the format is slightly different. In a Garlic Clove, messages are not fragmented, and the fragment bit in the flag byte is redefined. See the Garlic Clove documentation for more details.

In the black box it says:

bits 6-5: delivery type

For tunnel messages:

0x0 = LOCAL, 0x01 = TUNNEL, 0x02 = ROUTER, 0x03 = unused
Note: LOCAL is used for inbound tunnels only, unimplemented for outbound tunnels

For garlic cloves:

0x0 = LOCAL, 0x01 = DESTINATION, 0x02 = ROUTER, 0x03 = TUNNEL

I agree that it's too confusing. I will make the docs in tunnel-message for tunnel messages only, and add new docs in i2np for that version.

comment:7 Changed 5 years ago by zzz

re: comment 1, Oh yeah, I see, the fields are reversed.

comment:8 Changed 5 years ago by zzz

comment 1 fixed in d19c55c7887b96bf1bda4868976a623f94cc9e92

comment:9 Changed 5 years ago by zzz

Comment 3 was re: DH. Fixed in 232acf5af06668cc4dc225afa62f0f2f597dddef.

comment:10 Changed 5 years ago by zzz

@orignal, please provide pointers to the places in the tunnel docs that have the problems listed in the OP.

comment:11 in reply to: ↑ 5 Changed 5 years ago by orignal

Definitely I looked at this spec before Decemeber.
However I believe it's better to say that checksum is hash of payload + IV

Last edited 5 years ago by orignal (previous) (diff)

comment:12 Changed 5 years ago by orignal

https://geti2p.net/en/docs/spec/tunnel-creation

"bytes 104-135: AES-256 tunnel IV key"

It's not clear where do we take IV for IV encryption from.
Had to guess it's zero or just ECB mode

comment:13 follow-up: Changed 5 years ago by zzz

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

On http://i2p-projekt.i2p/en/docs/tunnels/implementation( participant processing section) it does specify ECB. I added a link to the email from 2005 that justified double-encryption of IV. I could not find any place where it talked about the IV encryption and didn't specify ECB.

On tunnel-creation, I added clarification that the layer key, IV key, reply key, and reply IV are all random values generated by the creator. I also clarified how the key and IV are used to encrypt each record. Is that sufficient?

On tunnel-message, I hopefully clarified the wording on the has of payload + IV.

in 097964b9720a7dd31d583607f84adfaa26e09b2c

comment:14 in reply to: ↑ 13 Changed 5 years ago by orignal

Well I agree it's there but on different page, also see the page
https://geti2p.net/en/docs/how/cryptography#AES
Not mentioning ECB.
Now look from developer's viewpoint.
You see reply key/reply IV, you also see layer key and it's clear IV comes with tunnel message, but wtf is IV key?
Indeed it's used for encryption/decryption of IV key in tunnel messages. But what IV we are supposed to use for this encryption? Remember we are still at the "Tunnel creation" page, looking into the cryptography page we can see CBC only.
In my opinion, ECB and double encryption should be specified explicitly there.

comment:15 Changed 5 years ago by orignal

https://geti2p.net/en/docs/spec/i2np#msg_DatabaseLookup

Should mention that encrypted reply will be garlic

comment:16 Changed 5 years ago by zzz

<iRelay> <orignal@freenode> you should state it will be garlic
<zzz> right
<iRelay> <orignal@freenode> because there is a confusion with "encrypted LeaseSet?"
<zzz> ok
<iRelay> <orignal@freenode> that's something else I even don't know what is it\
<zzz> I'm just wondering if it _really_ must be garlic, or if we could just encrypt the reply without wrapping it in a garlic
<iRelay> <orignal@freenode> that's my question as well
<iRelay> <orignal@freenode> I don't see reason why it must be garlic
<psi> try it
<iRelay> <orignal@freenode> try what?
<iRelay> <orignal@freenode> you can encrypt payload using session key
<iRelay> <orignal@freenode> then your party can try to decrypt it
<iRelay> <orignal@freenode> because it they expect encrypted reply they assume any DatabaseStore? coming through particular tunnel are encrypted
<iRelay> <orignal@freenode> with key associated with this tunnel
<zzz> it looks like our code in net.i2p.router.message is only set up to "garlic encrypt" GarlicMessages?. I think our specs allow for garlic encrypting other messages and maybe we would decrypt and handle them correctly, maybe not. But I don't think we send them.
<iRelay> <orignal@freenode> Than it shouldn't be "garlic" but "AES/ElGamal"
<iRelay> <orignal@freenode> Garlic mostly means cloves
<iRelay> <orignal@freenode> but AES/ElGamal means encryption method
<zzz> we document the "garlic" confusion here: http://i2p-projekt.i2p/en/docs/how/garlic-routing

Note: See TracTickets for help on using tickets.