Explain how the authenticity and integrity of a response is verified by IPFS.

[krishraghuram]

IPNS docs do not mention one thing that is not obvious to people who are relatively new to IPFS world.

TL;DR - document the details found on these discuss.ipfs.io posts into the IPNS docs page,

• https://discuss.ipfs.io/t/why-does-ipns-hash-the-public-key/8716
• https://discuss.ipfs.io/t/solved-how-to-verify-that-cid-is-signed-by-peerid/9140/24

Detailed

How the response of a ipfs name resolve <name> is verified? That is, how does ipfs client on my machine know that the peer I got the response from is not spoofing. In other words, how does the ipfs system prevent "ipns poisoning" attacks.

To be fair, the docs do contain,

A name in IPNS is the hash of a public key. It is associated with a record containing information about the hash it links to that is signed by the corresponding private key. New records can be signed and published at any time.

But the fact that the client only has the hash of the public key, and not the public key itself, confuses even people who are aware of digital signatures and how they work.

I had to dive deep into the aforementioned discuss.ipfs.io threads to find out that,

• IPNS name had to be hash of public key, because it was not possible to store entire 2048 bit RSA keys into the Kademlia DHT. The response of a ipns name resolve <name> will return the ipfs cid, signature and public key. Then the ipfs client does the following,

  • First, verify the integrity of public key, Hash(response.public_key) == IPNS name
  • Second, use the public key and signature to verify the ipfs cid, Decrypt(signature, public key) == ipfs cid

• With the launch of Ed25519 keys, the key itself can be stored into Kademlia DHT. So IPNS name contains the key itself, and so we can directly use that to verify the ipfs cid in the response. The first step where we verify the public key in the response goes away.

[welcome[bot]]

Thank you for submitting your first issue to this repository! A maintainer will be here shortly to triage and review. In the meantime, please double-check that you have provided all the necessary information to make this process easy! Any information that can help save additiona round trips is useful! We currently aim to give initial feedback within two business days. If this does not happen, feel free to leave a comment. Please keep an eye on how this issue will be labeled, as labels give an overview of priorities, assignments and additional actions requested by the maintainers:

• "Priority" labels will show how urgent this is for the team.
• "Status" labels will show if this is ready to be worked on, blocked, or in progress.
• "Need" labels will indicate if additional input or analysis is required.

Finally, remember to use https://discuss.ipfs.io if you just need general support.

[krishraghuram]

Hmm, I see that there is a general issue regarding improving IPNS docs page - https://github.com/ipfs/ipfs-docs/issues/244

I can dive deep into go-ipns code and confirm what I've stated above, and can also write decent docs for the same. Let me know if this is acceptable, or if you are only looking for someone to do a complete revamp of the IPNS docs page.