README
¶
[[ DEPRECATED ]] go-libp2p-conn
This package has been deprecated and is no longer used by go-libp2p. Now that transports are responsible for securing and multiplexing connections, the bulk of the logic in this package has been moved to go-libp2p-transport-upgrader, and the rest into go-libp2p-swarm.
- go-libp2p-swarm -- some of the dial logic
A library providing 'Connection' objects for libp2p.
This package offers wrappers for go-libp2p-transport raw types,
exposing go-libp2p-interface-conn types.
It negotiates either plaintext or secio over the raw connection
using go-multistream.
Table of Contents
Install
make deps
Usage
On the server side, a go-libp2p-transport Listener is wrapped in a go-libp2p-interface-conn Listener with WrapTransportListener. Such iconn.Listener has a peer identity: an ID and a secret key. These are only used when connections are encrypted, and a missing secret key forces plaintext connections.
On the client side, a Dialer creates go-libp2p-interface-conn connections using a set of go-libp2p-transport Dialers. Like with Listener, a Dialer has an ID and private key identity to be used to negotiate encrypted connections. Dial also checks the peer identity if encryption is enabled by specifying a secret key in Dialer.
Encryption is forced on when go-libp2p-interface-conn.EncryptConnections is true and the Dialer/Listener has a secret key, and forced off otherwise.
Protocol overview
The protocol is fairly straightforward: upon opening a connection, go-multistream is used to agree on plaintext ("/plaintext/1.0.0") or encrypted ("/secio/1.0.0"). Plaintext will only be negotiated iff both peers have go-libp2p-interface-conn.EncryptConnections set to false or haven't constructed their Listeners/Dialers with secret keys.
If plaintext is selected, the connection is used as-is for the rest of its lifetime.
If encrypted is selected, go-libp2p-secio is used to negotiate a transparent encrypted tunnel. The negotiation happens before the connection is made available to the library consumer.
Contribute
PRs are welcome!
Small note: If editing the Readme, please conform to the standard-readme specification.
Tests
make deps
go test
License
MIT © Jeromy Johnson
Documentation
¶
Index ¶
- Constants
- Variables
- func MultiaddrNetMatch(tgt ma.Multiaddr, srcs []ma.Multiaddr) ma.Multiaddr
- func MultiaddrProtocolsMatch(a, b ma.Multiaddr) bool
- func ReleaseBuffer(b []byte)
- func WrapTransportListener(ctx context.Context, ml transport.Listener, local peer.ID, sk ic.PrivKey) (iconn.Listener, error)
- func WrapTransportListenerWithProtector(ctx context.Context, ml transport.Listener, local peer.ID, sk ic.PrivKey, ...) (iconn.Listener, error)
- type ConnWrapper
- type Dialer
- type ListenerConnWrapper
Constants ¶
const ( SecioTag = "/secio/1.0.0" NoEncryptionTag = "/plaintext/1.0.0" )
Variables ¶
var AcceptTimeout = 60 * time.Second
AcceptTimeout is the maximum duration an Accept is allowed to take. This includes the time between accepting the raw network connection, protocol selection as well as the handshake, if applicable.
var DialTimeout = 60 * time.Second
DialTimeout is the maximum duration a Dial is allowed to take. This includes the time between dialing the raw network connection, protocol selection as well the handshake, if applicable.
Functions ¶
func MultiaddrNetMatch ¶
MultiaddrNetMatch returns the first Multiaddr found to match network.
func MultiaddrProtocolsMatch ¶
MultiaddrProtocolsMatch returns whether two multiaddrs match in protocol stacks.
func ReleaseBuffer ¶
func ReleaseBuffer(b []byte)
ReleaseBuffer puts the given byte array back into the appropriate global buffer pool based on its capacity.
func WrapTransportListener ¶
func WrapTransportListener(ctx context.Context, ml transport.Listener, local peer.ID, sk ic.PrivKey) (iconn.Listener, error)
WrapTransportListener wraps a raw transport.Listener in an iconn.Listener. If sk is not provided, transport encryption is disabled.
The Listener will accept connections in the background and attempt to negotiate the protocol before making the wrapped connection available to Accept. If the negotiation and handshake take more than AcceptTimeout, the connection is dropped. However, note that once a connection handshake succeeds, it will wait indefinitely for an Accept call to service it (possibly consuming a goroutine).
The context covers the listener and its background activities, but not the connections once returned from Accept. Calling Close and canceling the context are equivalent.
The returned Listener implements ListenerConnWrapper.
Types ¶
type ConnWrapper ¶
ConnWrapper is any function that wraps a raw multiaddr connection.
type Dialer ¶
type Dialer struct {
// LocalPeer is the identity of the local Peer.
LocalPeer peer.ID
// Dialers are the sub-dialers usable by this dialer,
// selected in order based on the address being dialed.
Dialers []transport.Dialer
// PrivateKey used to initialize a secure connection.
// Warning: if PrivateKey is nil, connection will not be secured.
PrivateKey ci.PrivKey
// Protector makes dialer part of a private network.
// It includes implementation details how connection are protected.
// Can be nil, then dialer is in public network.
Protector ipnet.Protector
// Wrapper to wrap the raw connection. Can be nil.
Wrapper ConnWrapper
// contains filtered or unexported fields
}
Dialer is an object with a peer identity that can open connections.
NewDialer must be used to instantiate new Dialer objects.
func NewDialer ¶
NewDialer creates a new Dialer object.
Before any calls to Dial are made, underlying dialers must be added with AddDialer, and Protector (if any) must be set.
func (*Dialer) AddDialer ¶
AddDialer adds a sub-dialer usable by this dialer. Dialers added first will be selected first, based on the address.
func (*Dialer) Dial ¶
func (d *Dialer) Dial(ctx context.Context, raddr ma.Multiaddr, remote peer.ID) (c iconn.Conn, err error)
Dial connects to a peer over a particular address. The remote peer ID is only verified if secure connections are in use. It returns once the connection is established, the protocol negotiated, and the handshake complete (if applicable).
type ListenerConnWrapper ¶
type ListenerConnWrapper interface {
// SetConnWrapper assigns a ConnWrapper to wrap all raw incoming
// connections with. It must be called before any call to Accept.
SetConnWrapper(ConnWrapper)
}
Source Files