secio

README

go-libp2p-secio

A secure transport module for go-libp2p

go-libp2p-secio is a component of the libp2p project, a modular networking stack for developing peer-to-peer applications. It provides a secure transport channel for go-libp2p. Following an initial plaintext handshake, all data exchanged between peers using go-libp2p-secio is encrypted and protected from eavesdropping.

libp2p supports multiple transport protocols, many of which lack native channel security. go-libp2p-secio is designed to work with go-libp2p's "transport upgrader", which applies security modules (like go-libp2p-secio) to an insecure channel. go-libp2p-secio implements the SecureTransport interface, which allows the upgrader to secure any underlying connection.

More detail on the handshake protocol and wire format used is available in the SECIO spec.

Install

Most people building applications with libp2p will have no need to install go-libp2p-secio directly. It is included as a dependency of the main go-libp2p "entry point" module and is enabled by default.

For users who do not depend on go-libp2p and are managing their libp2p module dependencies in a more manual fashion, go-libp2p-secio is a standard Go module which can be installed with:

go get github.com/libp2p/go-libp2p-secio

This repo is gomod-compatible, and users of go 1.11 and later with modules enabled will automatically pull the latest tagged release by referencing this package. Upgrades to future releases can be managed using go get, or by editing your go.mod file as described by the gomod documentation.

Usage

go-libp2p-secio is enabled by default when constructing a new libp2p Host, and it will be used to secure connections if both peers support it and agree to use it when establishing the connection.

You can disable SECIO by using the Security option when constructing a libp2p Host and passing in a different SecureTransport implementation, for example, go-libp2p-tls.

Transport security can be disabled for development and testing by passing the NoSecurity global Option.

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the libp2p Code of Conduct.

Want to hack on libp2p?

License

MIT

---

The last gx published version of this module was: 2.0.30: QmSVaJe1aRjc78cZARTtf4pqvXERYwihyYhZWoVWceHnsK

Documentation

Overview

Package secio is used to encrypt `go-libp2p-conn` connections. Connections wrapped by secio use secure sessions provided by this package to encrypt all traffic. A TLS-like handshake is used to setup the communication channel.

Index

• Constants
• Variables
• func NewETMReader(r io.Reader, s cipher.Stream, mac HMAC) msgio.ReadCloser
• func NewETMWriter(w io.Writer, s cipher.Stream, mac HMAC) msgio.WriteCloser
• type HMAC
• type Transport
  • func New(sk ci.PrivKey) (*Transport, error)
  • func (sg *Transport) SecureInbound(ctx context.Context, insecure net.Conn) (sec.SecureConn, error)
  • func (sg *Transport) SecureOutbound(ctx context.Context, insecure net.Conn, p peer.ID) (sec.SecureConn, error)

Constants

const DefaultSupportedCiphers = "AES-256,AES-128"

const DefaultSupportedExchanges = "P-256,P-384,P-521"

const DefaultSupportedHashes = "SHA256,SHA512"

const ID = "/secio/1.0.0"

ID is secio's protocol ID (used when negotiating with multistream)

Variables

var ErrBadSig = errors.New("bad signature")

ErrBadSig signals that the peer sent us a handshake packet with a bad signature.

var ErrClosed = errors.New("connection closed")

ErrClosed signals the closing of a connection.

var ErrEcho = errors.New("same keys and nonces. one side talking to self")

ErrEcho is returned when we're attempting to handshake with the same keys and nonces.

var ErrMACInvalid = errors.New("MAC verification failed")

ErrMACInvalid signals that a MAC verification failed

var ErrUnsupportedKeyType = errors.New("unsupported key type")

ErrUnsupportedKeyType is returned when a private key cast/type switch fails.

var ErrWrongPeer = errors.New("connected to wrong peer")

ErrWrongPeer is returned when we attempt to handshake with the wrong peer.

var HandshakeTimeout = time.Second * 30

HandshakeTimeout governs how long the handshake will be allowed to take place for. Making this number large means there could be many bogus connections waiting to timeout in flight. Typical handshakes take ~3RTTs, so it should be completed within seconds across a typical planet in the solar system.

var SupportedCiphers = DefaultSupportedCiphers

SupportedCiphers is the list of supported Ciphers

var SupportedExchanges = DefaultSupportedExchanges

SupportedExchanges is the list of supported ECDH curves

var SupportedHashes = DefaultSupportedHashes

SupportedHashes is the list of supported Hashes

Functions

func NewETMReader

func NewETMReader(r io.Reader, s cipher.Stream, mac HMAC) msgio.ReadCloser

NewETMReader Encrypt-Then-MAC

func NewETMWriter

func NewETMWriter(w io.Writer, s cipher.Stream, mac HMAC) msgio.WriteCloser

NewETMWriter Encrypt-Then-MAC

Types

type HMAC

type HMAC struct {
	hash.Hash
	// contains filtered or unexported fields
}

HMAC carries a hash and its size

type Transport

type Transport struct {
	LocalID    peer.ID
	PrivateKey ci.PrivKey
}

SessionGenerator constructs secure communication sessions for a peer.

func New

func New(sk ci.PrivKey) (*Transport, error)

func (*Transport) SecureInbound

func (sg *Transport) SecureInbound(ctx context.Context, insecure net.Conn) (sec.SecureConn, error)

func (*Transport) SecureOutbound

func (sg *Transport) SecureOutbound(ctx context.Context, insecure net.Conn, p peer.ID) (sec.SecureConn, error)