SECIO spec #106

bigs · 2018-10-24T21:36:18Z

Introduces a spec for SECIO. Various crypto algorithms living in *-libp2p-crypto have been omitted for the time being.

Stebalien

General comment: this reads more like a walk though the go-libp2p secio implementation and less like a spec. It would be nice if this were a bit more declarative (list out the message types, explain how they are composed, then explain how to use them) and less "run this, then this, then this".

Stebalien · 2018-10-24T23:05:44Z

secio/README.md

+proposal as follows:
+
+*Note: the public key should be serialized per the `Bytes` method from
+[go-libp2p-crypto](https://godoc.org/github.com/libp2p/go-libp2p-crypto#Key).*


Let's point at #100 (once it's merged)

Stebalien · 2018-10-24T23:06:22Z

secio/README.md

+  Pubkey: <public key bytes>,
+  Exchanges: <comma separated string of supported key exchanges>,
+  Ciphers: <comma separated string of supported ciphers>,
+  Hashes: <comma separated string of supported hashes>,


Let's put the actual protobuf here (and say that it's a protobuf).

Stebalien · 2018-10-24T23:07:15Z

secio/README.md

+
+Both peers serialize this message and send it over the wire. Upon deserializing
+their peer's message, they verify that the pubkey matches that described by the
+peer's peer ID (NOTE: this is sometimes only possible for the peer *initiating*


Given that this is just the spec, I'd just say:

At this point, each peer should check that the public key matches the expected peer ID, if known.

Or something like that. We don't need to explicitly tell the programmer how to implement the protocol step-by-step (i.e., "calculate the peer ID and store it for later").

Stebalien · 2018-10-24T23:11:36Z

secio/README.md

+Now the peers prepare a key exchange. Both peers generate an ephemeral key based
+on the agreed upon exchange (currently support is only available for elliptic
+curve algorithms). Ephemeral keys are generated via
+[go-libp2p-crypto](https://godoc.org/github.com/libp2p/go-libp2p-crypto#GenerateEKeyPair).


We should actually spec this.

That's standard ECDHE if I'm not mistaken.

Stebalien · 2018-10-24T23:12:50Z

secio/README.md

+  Epubkey: <ephemeral pubkey>,
+  Signature: <sign corpus with local private key>,
+}
+```


Again, let's just use the protobuf definition.

Stebalien · 2018-10-24T23:13:16Z

secio/README.md

+ephemeral key generation, passing it the remote peer's ephemeral key. With the
+shared secret generated, both peers stretch the key using the algorithm
+described by
+[go-libp2p-crypto](https://godoc.org/github.com/libp2p/go-libp2p-crypto#KeyStretcher).


Again, we need to spec this.

Stebalien · 2018-10-24T23:15:18Z

secio/README.md

+opened. Each packet is of the form:
+
+```
+[uint32 length of packet | encrypted body | hmac signature of encrypted body]


We encode the lengths as big-endian (network-order).

Need to specify what "encrypt" means.

Need to specify how we mac.

Does the padding style for encrypt need to be specified?

Really, we should specify everything. Ideally, we'd point to an RFC. However, we should optimize for merging something that's correct rather than waiting for something that's perfect.

I'm assuming that the length includes the encrypted body and the hmac signature.

tomaka · 2018-10-25T07:29:39Z

secio/README.md

+and `k2` the remote peer's key.
+
+Each peer now generates a MAC key and cipher for the remote and local keys
+generated in the previous step using the `MacKey` and `CipherKey` from the


Need to specify the order within the result of the stretching.

raulk · 2018-10-25T12:43:24Z

secio/README.md

+
+The SECIO wire protocol features two message types defined in the
+[protobuf description language](https://github.com/libp2p/go-libp2p-secio/blob/master/pb/spipe.proto).
+These two messages, `Propose` and `Exchange` are the only serialized types


Let's dump the current state of the protobufs here. Relying on a reference that can mutate can render the spec incoherent at a later time. Also, we're seeking to version specs in general, so capturing the current state and versioning the spec as it evolves is fair play.

Nevermind, I see this feedback is recurrent below.

raulk · 2018-10-25T12:46:57Z

secio/README.md

+
+### Proposal Generation
+
+SECIO channel negotiation begins with a proposal phase. Both sides generate a


As a prerequisite for SECIO, we need a dedicated channel where both parties have agreed to proceed with SECIO handshake by means of a multiplexer or else.

raulk · 2018-10-25T12:57:23Z

secio/README.md

+
+### Key Stretching
+
+Peers now generate their shared secret based on the function generated by the


IIRC, that function is referred to in literature as the KDF (key derivation function), and the overall process is called ECDH key agreement. Let's use these terms to evoke familiar concepts.

I think its official name is ECSVDP-DH

raulk · 2018-10-25T13:00:51Z

secio/README.md

+- P-384
+- P-521
+
+### Ciphers


Ciphers used for key stretching and for message encryption once SECIO channel is established.

Why is a deprecated cipher (Blowfish) supported? From the Go package docs:

Blowfish is a legacy cipher and its short block size makes it vulnerable to birthday bound attacks (see https://sweet32.info). It should only be used where compatibility with legacy systems, not security, is the goal.

Deprecated: any new system should use AES (from crypto/aes, if necessary in an AEAD mode like crypto/cipher.NewGCM) or XChaCha20-Poly1305 (from golang.org/x/crypto/chacha20poly1305).

Since the spec is not yet finalized, it would be cool if support was removed. If there is some mitigating circumstance (I haven't gone through the source very thoroughly!), a note about it would be helpful.

It would also be worth noting what mode the AES ciphers should use. From the Go implementation, it looks like it's CTR!

Also, more generally, is this an implementation of any well-reviewed specification? If not, is there a reason why? I would imagine there are a number of specs for low-overhead, encrypted channels which may prevent future pitfalls.

This is definitely not well-reviewed and will be will be deprecated in favor of TLS quite soon. See: https://github.com/libp2p/go-libp2p-tls/.

(go-ipfs now has experimental support which we'll likely upgrade to default support after a release or two).

Gotcha, makes sense! And that answers my follow-up questions as well :)

raulk · 2018-10-25T13:02:02Z

secio/README.md

+SECIO allows participating peers to support a subset of the following
+algorithms.
+
+### Exhchanges


Elliptic curves used for ephemeral key generation.

raulk · 2018-10-25T13:02:28Z

secio/README.md

+- AES-128
+- Blowfish
+
+### Hashes


Hashes used for key stretching, and for HMACs once SECIO channel is established.

What mode and padding is AES-* using? Are there any parameters for Blowfish?

raulk · 2018-10-25T13:10:08Z

secio/README.md

+preferred peer. After swapping if necessary, `k1` becomes the local peer's key
+and `k2` the remote peer's key.
+
+Each peer now generates a MAC key and cipher for the remote and local keys


These are not generated here. The MAC key is already generated during key stretching above. The cipher was selected above when comparing Propose messages.

What the Go implementation does at this point is prepare the constructs for HMAC and encryption/decryption. I think that's what needs to be stated, i.e. the implementation now has the required parameters to initialise the cryptographic constructs.

raulk · 2018-10-25T13:18:16Z

secio/README.md

+```
+
+The first packet transmitted by each peer must be the remote peer's nonce. Peers
+validate that the remote peer sent them their nonce, closing if unsuccessful.


The target of validation is actually the (d)encryption and HMAC'ing logic. We use a known value (nonce) to send a predictable message so we can validate that both parties have set up the encrypted channels correctly.

raulk · 2018-11-07T18:18:42Z

secio/README.md

+
+## Table of Contents
+
+- [Algorithm Support](#algorithm-support)


ToC is missing entries.

richardschneider · 2018-11-10T22:34:54Z

secio/README.md

+### Hashes
+
+- SHA-256
+- SHA-512


Current go implementation does not use dashes in the hash name; see al.go.

whyrusleeping · 2018-11-11T20:25:55Z

@bigs status on this? Are you planning on continuing this work in the near future?

bigs · 2018-11-12T16:13:32Z

yep @whyrusleeping just lower priority than testbed work at the moment. lotta good feedback re: shaping this into a more formal spec

yusefnapora · 2019-05-08T20:14:33Z

secio/README.md

+exchanges. Each peer computes:
+
+```
+oh1 := sha256(concat(remotePeerPubKeyBytes, myNonce))


This is the first use of the word "nonce". Does it refer to the rand field of the Propose message?

yusefnapora · 2019-05-09T18:13:48Z

Hey all, I took a stab at addressing the review feedback here. I'd love if people with more experience could give it a review.

One thing I didn't address was using more standard nomenclature (e.g. KDF, ECDH), as I'm not super confident I'd use the terms correctly. I might read up a bit more and give that a go for the next round.

bigs

i can't approve since i technically opened the PR. i say we add a DRAFT notice to the top and merge as is. what remains is really a few passes to add detail.

yusefnapora · 2019-06-11T15:12:50Z

I'm going to go ahead and merge this, since I think it's in a decent state. If I added anyone to the interest group (@Stebalien, @richardschneider, @tomaka, @raulk) that doesn't want to be there, let me know.

bigs added 2 commits October 24, 2018 21:36

Initial transcription work

0dc2992

Finish first pass of SECIO spec

2194c68

bigs requested review from Stebalien and raulk October 24, 2018 21:36

ghost assigned bigs Oct 24, 2018

ghost added the in progress label Oct 24, 2018

Stebalien reviewed Oct 24, 2018

View reviewed changes

tomaka suggested changes Oct 25, 2018

View reviewed changes

raulk requested changes Oct 25, 2018

View reviewed changes

raulk reviewed Nov 7, 2018

View reviewed changes

secio/README.md Outdated

## Table of Contents

- [Algorithm Support](#algorithm-support)

Copy link

Member

raulk Nov 7, 2018

Choose a reason for hiding this comment

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

ToC is missing entries.

richardschneider reviewed Nov 10, 2018

View reviewed changes

marten-seemann mentioned this pull request Nov 14, 2018

add a QUIC blog post ipfs-inactive/blog#194

Closed

Stebalien mentioned this pull request Nov 16, 2018

Is there a secio formal spec libp2p/go-libp2p-secio#13

Closed

ghost mentioned this pull request Nov 19, 2018

Specs 2.0 & libp2p book #110

Open

16 tasks

marten-seemann mentioned this pull request Mar 7, 2019

Specifications for SECIO #152

Closed

yusefnapora reviewed May 8, 2019

View reviewed changes

yusefnapora added 3 commits May 9, 2019 12:20

address review feedback

3497da6

generate TOC

029798f

more detail about secure packet contents & initial verification

0c0a2aa

ghost assigned yusefnapora May 9, 2019

small fix

c73bc5d

bigs commented May 21, 2019

View reviewed changes

add DRAFT status notice

a727256

yusefnapora mentioned this pull request May 22, 2019

libp2p specification framework – lifecycle: maturity level and status #169

Merged

yusefnapora added 3 commits May 22, 2019 11:06

set status to 3A and link to lifecycle doc

9264cea

add lifecycle header & regenerate TOC

2c7fe93

use shortcut reference links for authors in header

1443ebf

yusefnapora mentioned this pull request May 27, 2019

libp2p specs framework: document header format #171

Merged

yusefnapora added the maturity:recommendation Promotes a spec from Candidate Recommendation to Recommendation label May 27, 2019

yusefnapora merged commit effa408 into master Jun 11, 2019

yusefnapora deleted the feat/specio branch June 11, 2019 15:13


		### Proposal Generation

		SECIO channel negotiation begins with a proposal phase. Both sides generate a


		### Key Stretching

		Peers now generate their shared secret based on the function generated by the


		## Table of Contents

		- [Algorithm Support](#algorithm-support)

SECIO spec #106

SECIO spec #106

Conversation

bigs commented Oct 24, 2018

Stebalien left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richardschneider Nov 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GriffinMB Apr 11, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raulk Oct 25, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whyrusleeping commented Nov 11, 2018

bigs commented Nov 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yusefnapora commented May 9, 2019

bigs left a comment

Choose a reason for hiding this comment

yusefnapora commented Jun 11, 2019

richardschneider Nov 13, 2018 •

edited

Loading

GriffinMB Apr 11, 2019 •

edited

Loading

raulk Oct 25, 2018 •

edited

Loading