noise

package module
v0.0.0-...-e795a0a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 5, 2019 License: MIT Imports: 18 Imported by: 0

README

Noise

GoDoc Discord MIT licensed Build Status Go Report Card Coverage Statusd

noise is an opinionated, easy-to-use P2P network stack for decentralized applications, and cryptographic protocols written in Go by the Perlin team.

noise is made to be robust, developer-friendly, performant, secure, and cross-platform across multitudes of devices by making use of well-tested, production-grade dependencies.

By itself, noise is a low-level, stateless, concurrent networking library that easily allows you to incorporate fundamental features any modern p2p application needs such as:

  1. cryptographic primitives (Ed25519, PoW, AES-256),
  2. message serialization/deserialization schemes (byte-order little endian, protobuf, msgpack),
  3. network timeout/error management (on dial, on receive message, on send buffer full),
  4. network-level atomic operations (receive-then-lock),
  5. and NAT traversal support (NAT-PMP, UPnP).

Out of its own low-level constructs, noise additionally comes bundled with a high-level protocol package comprised of a large number of production-ready, high-level protocol building blocks such as:

  1. handshake protocol implementations (Elliptic-Curve Diffie Hellman),
  2. peer routing/discovery protocol implementations (S/Kademlia),
  3. message broadcasting protocol implementations (S/Kademlia),
  4. overlay network protocol implementations (S/Kademlia),
  5. cryptographic identity schemes (Ed25519 w/ EdDSA signatures),
  6. and authenticated encryption schemes (AES-256 GCM AEAD).

Every single building block is easily configurable, and may be mixed and matched together to help you kickstart your journey on developing secure, debuggable, and highly-performant p2p applications.

package main

import (
    "fmt"
	
    "github.com/perlin-network/noise"
    "github.com/perlin-network/noise/cipher/aead"
    "github.com/perlin-network/noise/handshake/ecdh"
    "github.com/perlin-network/noise/identity/ed25519"
    "github.com/perlin-network/noise/protocol"
    "github.com/perlin-network/noise/rpc"
    "github.com/perlin-network/noise/skademlia"
)

type chatMessage struct {
	text string
}

func (chatMessage) Read(reader payload.Reader) (noise.Message, error) {
	text, err := reader.ReadString()
	if err != nil {
		return nil, errors.Wrap(err, "failed to read chat msg")
	}

	return chatMessage{text: text}, nil
}

func (m chatMessage) Write() []byte {
	return payload.NewWriter(nil).WriteString(m.text).Bytes()
}

func main() {
    // Register message type to Noise.
    opcodeChatMessage := noise.RegisterMessage(noise.NextAvailableOpcode(), (*chatMessage)(nil))
    
    params := noise.DefaultParams()
    params.Keys = ed25519.Random()
    params.Port = uint16(3000)
    
    node, err := noise.NewNode(params)
    if err != nil {
        panic(err)
    }
    
    protocol.New().
    	Register(ecdh.New()).
    	Register(aead.New()).
    	Register(skademlia.New()).
    	Enforce(node)
    
    fmt.Printf("Listening for peers on port %d.\n", node.ExternalPort())
    
    go node.Listen()
    
    // Dial peer via TCP located at address 127.0.0.1:3001.
    peer, err := node.Dial("127.0.0.1:3001")
    if err != nil {
        panic(err)
    }
    
    // Wait until the peer has finished all cryptographic handshake procedures.
    skademlia.WaitUntilAuthenticated(peer)
    
    // Send a single chat message over the peer knowing that it's encrypted over the wire.
    err = peer.SendMessage(chatMessage{text: "Hello peer!"})
    if err != nil {
        panic(err)
    }
    
    // Receive and print out a single chat message back from our peer.
    fmt.Println(<-peer.Receive(opcodeChatMessage))
}

Setup

Make sure to have at the bare minimum Go 1.11 installed before incorporating noise into your project.

After installing Go, you may choose to either:

  1. directly incorporate noise as a library dependency to your project,
# Be sure to have Go modules enabled: https://github.com/golang/go/wiki/Modules
export GO111MODULE=on

# Run this inside your projects directory.
go get github.com/perlin-network/noise
  1. or checkout the source code on Github and run any of the following commands below.
# Be sure to have Go modules enabled: https://github.com/golang/go/wiki/Modules
export GO111MODULE=on

# Run an example creating a cluster of 3 peers automatically
# discovering one another.
[terminal 1] go run examples/chat/main.go -p 3000
[terminal 2] go run examples/chat/main.go -p 3001 127.0.0.1:3000
[terminal 3] go run examples/chat/main.go -p 3002 127.0.0.1:3001

# Optionally run test cases.
go test -v -count=1 -race ./...

We're hiring!

Here at Perlin, we spend days and weeks debating, tinkering, and researching what is out there in academia to bring to industries truly resilient, open-source, secure, economic, and decentralized software to empower companies, startups, and users.

Our doors are open to academics that have a knack for distributed systems, engineers that want to explore unknown waters, frontend developers that want to make and evangelize the next generation of customer-facing applications, and graphics designers that yearn to instrument together greater user experiences for decentralized applications.

Contributions

First of all, thank you so much for taking part in our efforts for creating a p2p networking stack that can meet everyones needs without sacrificing developer productivity!

All code contributions to noise should comply with all idiomatic Go standards listed here.

All commit messages should be in the format:

module_name_1, module_name_2: description of the changes you made to the two
    modules here as a sentence

Be sure to use only imperative, present tense within your commit messages and optionally include motivation for your changes two lines breaks away from your commit message.

This allows other maintainers and contributors to know which modules you are modifying/creating within the code/docs repository.

Lastly, be sure to consider backwards compatibility.

New modules/methods are perfectly fine, but changing code living in noise.Node or noise.Peer radically for example would break a lot of existing projects utilizing noise.

Additionally, if you'd like to talk to us or any of the team in real-time, be sure to join our Discord server!

We are heavily active, ready to answer any questions/assist you with any code/doc contributions at almost any time.

License

noise, and all of its source code is released under the MIT License.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DebugOpcodes 

func DebugOpcodes()

DebugOpcodes prints out all opcodes registered to Noise thus far.

func DefaultParams 

func DefaultParams() parameters

Types

type AfterMessageEncodedCallback 

type AfterMessageEncodedCallback func(node *Node, peer *Peer, header, msg []byte) ([]byte, error)

type AfterMessageReceivedCallback 

type AfterMessageReceivedCallback func(node *Node, peer *Peer) error

type AfterMessageSentCallback 

type AfterMessageSentCallback func(node *Node, peer *Peer) error

type BeforeMessageReceivedCallback 

type BeforeMessageReceivedCallback func(node *Node, peer *Peer, msg []byte) ([]byte, error)

type BeforeMessageSentCallback 

type BeforeMessageSentCallback func(node *Node, peer *Peer, msg []byte) ([]byte, error)

type EmptyMessage 

type EmptyMessage struct{}

func (EmptyMessage) Read 

func (EmptyMessage) Read(reader payload.Reader) (Message, error)

func (EmptyMessage) Write 

func (EmptyMessage) Write() []byte

type Message 

type Message interface {
	Read(reader payload.Reader) (Message, error)
	Write() []byte
}

To have Noise send/receive messages of a given type, said type must implement the following Message interface.

Noise by default encodes messages as bytes in little-endian order, and provides utility classes to assist with serializing/deserializing arbitrary Go types into bytes efficiently.

By exposing raw network packets as bytes to users, any additional form of serialization or message packing or compression scheme or cipher scheme may be bootstrapped on top of any particular message type registered to Noise.

func MessageFromOpcode 

func MessageFromOpcode(opcode Opcode) (Message, error)

MessageFromOpcode returns an empty message representation associated to a registered message opcode.

It errors if the specified message opcode is not registered to Noise.

type Node 

type Node struct {
	Keys identity.Keypair
	// contains filtered or unexported fields
}

func NewNode 

func NewNode(params parameters) (*Node, error)

func (*Node) Delete 

func (n *Node) Delete(key string)

func (*Node) Dial 

func (n *Node) Dial(address string) (*Peer, error)

Dial has our node attempt to dial and establish a connection with a remote peer.

func (*Node) ExternalAddress 

func (n *Node) ExternalAddress() string

func (*Node) ExternalPort 

func (n *Node) ExternalPort() uint16

func (*Node) Fence 

func (n *Node) Fence()

Fence blocks the current goroutine until the node stops listening for peers.

func (*Node) Get 

func (n *Node) Get(key string) interface{}

Get returns the value to a metadata key from our node, or otherwise returns nil should there be no corresponding value to a provided key.

func (*Node) Has 

func (n *Node) Has(key string) bool

func (*Node) InternalPort 

func (n *Node) InternalPort() uint16

func (*Node) Kill 

func (n *Node) Kill()

func (*Node) Listen 

func (n *Node) Listen()

Listen makes our node start listening for peers.

func (*Node) LoadOrStore 

func (n *Node) LoadOrStore(key string, val interface{}) interface{}

func (*Node) OnListenerError 

func (n *Node) OnListenerError(c OnErrorCallback)

OnListenerError registers a callback for whenever our nodes listener fails to accept an incoming peer.

func (*Node) OnPeerConnected 

func (n *Node) OnPeerConnected(c OnPeerInitCallback)

OnPeerConnected registers a callback for whenever a peer has successfully been accepted by our node.

func (*Node) OnPeerDialed 

func (n *Node) OnPeerDialed(c OnPeerInitCallback)

OnPeerDialed registers a callback for whenever a peer has been successfully dialed.

func (*Node) OnPeerDisconnected 

func (n *Node) OnPeerDisconnected(srcCallbacks ...OnPeerDisconnectCallback)

OnPeerDisconnected registers a callback whenever a peer has been disconnected.

func (*Node) OnPeerInit 

func (n *Node) OnPeerInit(srcCallbacks ...OnPeerInitCallback)

OnPeerInit registers a callback for whenever a peer has either been successfully dialed, or otherwise accepted by our node.

In essence a helper function that registers callbacks for both `OnPeerConnected` and `OnPeerDialed` at once.

func (*Node) Set 

func (n *Node) Set(key string, val interface{})

Set sets a metadata entry given a key-value pair on our node.

type OnErrorCallback 

type OnErrorCallback func(node *Node, err error) error

type OnMessageReceivedCallback 

type OnMessageReceivedCallback func(node *Node, opcode Opcode, peer *Peer, message Message) error

type OnPeerDecodeFooterCallback 

type OnPeerDecodeFooterCallback func(node *Node, peer *Peer, msg []byte, reader payload.Reader) error

type OnPeerDecodeHeaderCallback 

type OnPeerDecodeHeaderCallback func(node *Node, peer *Peer, reader payload.Reader) error

type OnPeerDisconnectCallback 

type OnPeerDisconnectCallback func(node *Node, peer *Peer) error

type OnPeerErrorCallback 

type OnPeerErrorCallback func(node *Node, peer *Peer, err error) error

type OnPeerInitCallback 

type OnPeerInitCallback func(node *Node, peer *Peer) error

type Opcode 

type Opcode byte
const (
	OpcodeNil Opcode = 0
)

func NextAvailableOpcode 

func NextAvailableOpcode() Opcode

NextAvailableOpcode returns the next available unregistered message opcode registered to Noise.

func OpcodeFromMessage 

func OpcodeFromMessage(msg Message) (Opcode, error)

OpcodeFromMessage uses reflection to extract and return the opcode associated to a message value type.

It errors if the specified message value type is not registered to Noise.

func RegisterMessage 

func RegisterMessage(o Opcode, m interface{}) Opcode

func (Opcode) Bytes 

func (o Opcode) Bytes() (buf [1]byte)

Bytes returns this opcodes' byte representation.

type Peer 

type Peer struct {
	// contains filtered or unexported fields
}

func (*Peer) AfterMessageReceived 

func (p *Peer) AfterMessageReceived(c AfterMessageReceivedCallback)

AfterMessageReceived registers a callback to be called after a message is to be received from a specified peer.

func (*Peer) AfterMessageSent 

func (p *Peer) AfterMessageSent(c AfterMessageSentCallback)

AfterMessageSent registers a callback to be called after a message is sent to a specified peer.

func (*Peer) BeforeMessageReceived 

func (p *Peer) BeforeMessageReceived(c BeforeMessageReceivedCallback)

BeforeMessageReceived registers a callback to be called before a message is to be received from a specified peer.

func (*Peer) BeforeMessageSent 

func (p *Peer) BeforeMessageSent(c BeforeMessageSentCallback)

BeforeMessageSent registers a callback to be called before a message is sent to a specified peer.

func (*Peer) DecodeMessage 

func (p *Peer) DecodeMessage(buf []byte) (Opcode, Message, error)

func (*Peer) Delete 

func (p *Peer) Delete(key string)

func (*Peer) Disconnect 

func (p *Peer) Disconnect()

func (*Peer) DisconnectAsync 

func (p *Peer) DisconnectAsync() <-chan struct{}

func (*Peer) EncodeMessage 

func (p *Peer) EncodeMessage(message Message) ([]byte, error)

EncodeMessage serializes a message body into its byte representation, and prefixes said byte representation with the messages opcode for the purpose of sending said bytes over the wire.

Additional header/footer bytes is prepended/appended accordingly.

Refer to the functions `OnEncodeHeader` and `OnEncodeFooter` available in `noise.Peer` to prepend/append additional information on every single message sent over the wire.

func (*Peer) Get 

func (p *Peer) Get(key string) interface{}

Get returns the value to a metadata key from our node, or otherwise returns nil should there be no corresponding value to a provided key.

func (*Peer) Has 

func (p *Peer) Has(key string) bool

func (*Peer) LoadOrStore 

func (p *Peer) LoadOrStore(key string, val interface{}) interface{}

func (*Peer) LocalIP 

func (p *Peer) LocalIP() net.IP

func (*Peer) LocalPort 

func (p *Peer) LocalPort() uint16

func (*Peer) LockOnReceive 

func (p *Peer) LockOnReceive(opcode Opcode) receiveHandle

func (*Peer) Node 

func (p *Peer) Node() *Node

func (*Peer) OnConnError 

func (p *Peer) OnConnError(c OnPeerErrorCallback)

OnConnError registers a callback for whenever something goes wrong with the connection to our peer.

func (*Peer) OnDecodeFooter 

func (p *Peer) OnDecodeFooter(c OnPeerDecodeFooterCallback)

OnDecodeFooter registers a callback that is fed in the contents of the footer portion of an incoming message from a specified peer.

func (*Peer) OnDecodeHeader 

func (p *Peer) OnDecodeHeader(c OnPeerDecodeHeaderCallback)

OnDecodeHeader registers a callback that is fed in the contents of the header portion of an incoming message from a specified peer.

func (*Peer) OnDisconnect 

func (p *Peer) OnDisconnect(srcCallbacks ...OnPeerDisconnectCallback)

OnDisconnect registers a callback for whenever the peer disconnects.

func (*Peer) OnEncodeFooter 

func (p *Peer) OnEncodeFooter(c AfterMessageEncodedCallback)

OnEncodeFooter registers a callback that is fed in the raw contents of a message to be sent, which then outputs bytes that are to be appended to the footer of an outgoing message.

func (*Peer) OnEncodeHeader 

func (p *Peer) OnEncodeHeader(c AfterMessageEncodedCallback)

OnEncodeHeader registers a callback that is fed in the raw contents of a message to be sent, which then outputs bytes that are to be appended to the header of an outgoing message.

func (*Peer) Receive 

func (p *Peer) Receive(o Opcode) <-chan Message

func (*Peer) RemoteIP 

func (p *Peer) RemoteIP() net.IP

func (*Peer) RemotePort 

func (p *Peer) RemotePort() uint16

func (*Peer) SendMessage 

func (p *Peer) SendMessage(message Message) error

SendMessage sends a message whose type is registered with Noise to a specified peer. Calling this function will block the current goroutine until the message is successfully sent. In order to not block, refer to `SendMessageAsync(message Message) <-chan error`.

It is guaranteed that all messages are sent in a linearized order.

It returns an error should it take too long to send a message, the message is not registered with Noise, or there are message that are blocking the peers send worker.

func (*Peer) SendMessageAsync 

func (p *Peer) SendMessageAsync(message Message) <-chan error

SendMessageAsync sends a message whose type is registered with Noise to a specified peer. Calling this function will not block the current goroutine until the message is successfully sent. In order to block, refer to `SendMessage(message Message) error`.

It is guaranteed that all messages are sent in a linearized order.

It returns an error should the message not be registered with Noise, or there are message that are blocking the peers send worker.

func (*Peer) Set 

func (p *Peer) Set(key string, val interface{})

Set sets a metadata entry given a key-value pair on our node.

func (*Peer) SetNode 

func (p *Peer) SetNode(node *Node)

Source Files

View all Source files

Directories

Path Synopsis
cipher
aead
examples
benchmark
chat
e2e
handshake
ecdh
ed25519
internal
bufconn
Package bufconn provides a net.Conn implemented by a buffer and related dialing and listening functionality.
 Package bufconn provides a net.Conn implemented by a buffer and related dialing and listening functionality.
edwards25519
Package ed25519 implements the Ed25519 signature algorithm.
 Package ed25519 implements the Ed25519 signature algorithm.
eddsa

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.