Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add peer id spec #100

Merged
merged 24 commits into from
Jun 20, 2019
Merged

docs: add peer id spec #100

Changes from 1 commit
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
714a6c7
docs: add peer id spec
Oct 10, 2018
565767a
docs: clean up writing
Oct 10, 2018
902fbfe
docs: fix @vyzo comment
Oct 10, 2018
95c2354
docs: syntax highlighting
Oct 10, 2018
d8459bc
Key types should/may
Oct 11, 2018
e2dfbe2
clarify 42 byte rule
Oct 12, 2018
6c318c9
remove references to private keys & storage formats
yusefnapora Mar 14, 2019
878f2fa
remove links to go impl, add links to specs
yusefnapora Mar 14, 2019
eda2295
peer ids: language nit
raulk Mar 15, 2019
242afbe
bring back private keys, add context about serialization
yusefnapora Mar 19, 2019
52057ac
base key types MUST be supported
yusefnapora Mar 19, 2019
3302991
peer id: implementations may configure key types
raulk Mar 27, 2019
f277f41
note that we're using proto2
yusefnapora May 8, 2019
046c7e8
soon has come :)
yusefnapora May 8, 2019
9bfb370
mention we're not using multibase for peer-ids
yusefnapora May 8, 2019
a7de2f6
tweak the description of peer id generation
yusefnapora May 8, 2019
1237100
add note about deterministic encoding of PublicKey protobuf
yusefnapora May 8, 2019
870b71a
revise note about deterministic encoding
yusefnapora May 22, 2019
d14a44d
update status & generate TOC
yusefnapora May 22, 2019
10043ec
fix TOC
yusefnapora May 22, 2019
6c4a587
update status header
yusefnapora May 23, 2019
2ec0867
use shortcut reference links for authors in header
yusefnapora May 27, 2019
5173834
Merge master into feat/peer-ids
yusefnapora Jun 19, 2019
ed01eb1
add peer id spec to index
yusefnapora Jun 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions peer-ids/peer-ids.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Keys


Everything is based on a very simple protobuf in [libp2p/go-libp2p-crypto/pb/crypto.proto#L5](https://github.com/libp2p/go-libp2p-crypto/blob/master/pb/crypto.proto#L5):
Our key pairs are transmitted on the wire using a simple protobuf defined in [libp2p/go-libp2p-crypto/pb/crypto.proto#L5](https://github.com/libp2p/go-libp2p-crypto/blob/master/pb/crypto.proto#L5):
This conversation was marked as resolved.
Show resolved Hide resolved

```
This conversation was marked as resolved.
Show resolved Hide resolved
enum KeyType {
Expand All @@ -24,16 +24,16 @@ message PrivateKey {
}
```

As you can see, this proto simply transmits a public/private key pair along with an enum specifying the type of keypair.
As should be apparent from the above code block, this proto simply encodes for transmission a public/private key pair along with an enum specifying the type of keypair.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any situation where we want to transmit the PrivateKey? That seems... dangerous. If not, we don't need to specify the PrivateKey here at all.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, storage of private key is implementation specific, so no need to cover them in this doc I think.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, users do need to be able to take their private keys with them (especially because we use these for things like IPNS).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's true that removing the private key format from this doc leaves a gap. We still need to specify somewhere how we handle them.

We could bring back the private key references and add a call-out at the top of the doc that they're not related to peer-id calculation and are shown for reference.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really, we should probably rename this doc to the "libp2p key spec" and make peer ID calculation a part of that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 for that


#### Where it's used?

In libp2p for signing messages. Categories of messages we sign:
Keys are used in two places in libp2p. The first is for signing messages. Here are some examples of messages we sign:
- IPNS records
- PubSub messages (coming soon)
- SECIO handshake

We also use these protos for generating peer ids, as discussed in the section below.
The second is for generating peer ids; this is discussed in the section below.

## Peer Ids

Expand All @@ -44,7 +44,7 @@ Here is the process by which we generate peer id's based on the public/private k
3. If the length of the serialized bytes <= 42, then we compute the "identity" multihash of the serialized bytes. In other words, no hashing is performed, but the [multihash format is still followed](https://github.com/multiformats/multihash) (byte plus varint plus serialized bytes). The idea here is that if the serialized byte array is short enough, we can fit it in a multihash proto without having to condense it using a hash function.
Stebalien marked this conversation as resolved.
Show resolved Hide resolved
4. If the length is >42, then we hash it using it using the SHA256 multihash.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should say something about how these are commonly represented as strings: base58btc encoding raw, without using multibase.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a bit about base58btc, but didn't mention multibase, since we hadn't defined it yet in the doc. Should I bring it up? I think if people are likely to expect Peer Ids to use multibase we should clarify.


## How Keys are Encoded
## How Keys are Encoded and Messages Signed

Keys are passed around in code as byte arrays. Keys are encoded within these arrays differently depending on the type of key.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems like an implementation decision. Remove this sentence?


Expand Down