conn

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
• Usage
• Protocol overview
• Contribute
• License

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
  • func NewDialer(p peer.ID, pk ci.PrivKey, wrap ConnWrapper) *Dialer
  • func (d *Dialer) AddDialer(pd transport.Dialer)
  • func (d *Dialer) Dial(ctx context.Context, raddr ma.Multiaddr, remote peer.ID) (c iconn.Conn, err error)
  • func (d *Dialer) String() string
• 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

func MultiaddrNetMatch(tgt ma.Multiaddr, srcs []ma.Multiaddr) ma.Multiaddr

MultiaddrNetMatch returns the first Multiaddr found to match network.

func MultiaddrProtocolsMatch

func MultiaddrProtocolsMatch(a, b ma.Multiaddr) bool

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.

func WrapTransportListenerWithProtector

func WrapTransportListenerWithProtector(ctx context.Context, ml transport.Listener, local peer.ID,
	sk ic.PrivKey, protec ipnet.Protector) (iconn.Listener, error)

Types

type ConnWrapper

type ConnWrapper func(transport.Conn) transport.Conn

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

func NewDialer(p peer.ID, pk ci.PrivKey, wrap ConnWrapper) *Dialer

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

func (d *Dialer) AddDialer(pd transport.Dialer)

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).

func (*Dialer) String

func (d *Dialer) String() string

String returns the string representation of this Dialer.

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)
}