An easy-to-use XChaCha20-encryption wrapper for io.ReadWriteCloser (even lossy UDP) using ECDH key exchange algorithm, ED25519 signatures and Blake3+Poly1305 checksums/message-authentication for Go (golang). Also a multiplexer.


GoDoc go report Build Status Coverage Status

Quick start

Prepare keys (on both sides):

[ -f ~/.ssh/id_ed25519 ] && [ -f ~/.ssh/ ] || ssh-keygen -t ed25519
scp ~/.ssh/ remote:from_remote_side/

Encrypted io.ReadWriteCloser, easy:

// Generate (if not exists) and read ED25519 keys 
identity, err := secureio.NewIdentity(`/home/user/.ssh`)

// Read remote identity 
remoteIdentity, err := secureio.NewRemoteIdentityFromPublicKey(`/home/user/from_remote_side/`)

// Create a connection
conn, err := net.Dial("udp", "")

// Create an encrypted connection (and exchange keys using ECDH and verify remote side by ED25519 signature).
session := identity.NewSession(remoteIdentity, conn, nil, nil)

// Use it!

// Write to it
_, err = session.Write(someData)

// Or/and read from it
_, err = session.Read(someData)

It's also a multiplexer


Setup the receiver:

session.SetHandlerFuncs(secureio.MessageTypeChannel(0), func(payload []byte) {
    fmt.Println("I received a payload:", payload)
}, func(err error) {


Send a message synchronously:

_, err := session.WriteMessage(secureio.MessageTypeChannel(0), payload)


Send a message asynchronously:

// Schedule the sending of the payload
sendInfo := session.WriteMessageAsync(secureio.MessageTypeChannel(0), payload)

[.. your another stuff here if you want ..]

// Wait until the real sending

// Here you get the error if any:
err := sendInfo.Err

// It's not necessary, but helps to reduce the pressure on GC (so to optimize CPU and RAM utilization)


A MessageType for a custom channel may be created via function MessageTypeChannel(channelID uint32). channelID is a custom number to identify which flow is it (to connect a sender with appropriate receiver on the remote side). In the examples above it was used 0 as the channelID value, but it could be any value in the range: 0 <= x <= 2**31.

Also there's a special MessageType MessageTypeReadWrite is used for default Read()/Write(). But you may redirect this flow to a custom handler.

Limitations and hints

  • Does not support traffic fragmentation. If it's required to make it work over UDP then it's required to disable the fragmentation, see an example for UDP.
  • If the underlying writer cannot handle big messages then it's required to adjust SessionOptions.MaxPayloadSize.
  • If you don't have multiple writers and you don't need to aggregate messages (see below) then you may set SessionOptions.SendDelay to &[]time.Duration{0}[0].


The benchmark was performed with communication via an UNIX-socket.

BenchmarkSessionWriteRead1-8                          	   10000	    118153 ns/op	   0.01 MB/s	     468 B/op	       8 allocs/op
BenchmarkSessionWriteRead16-8                         	   10000	    118019 ns/op	   0.14 MB/s	     455 B/op	       8 allocs/op
BenchmarkSessionWriteRead1024-8                       	    9710	    119238 ns/op	   8.59 MB/s	     441 B/op	       8 allocs/op
BenchmarkSessionWriteRead32000-8                      	    6980	    173441 ns/op	 184.50 MB/s	     488 B/op	       9 allocs/op
BenchmarkSessionWriteRead64000-8                      	    3994	    310038 ns/op	 206.43 MB/s	     629 B/op	       9 allocs/op
BenchmarkSessionWriteMessageAsyncRead1-8              	 2285032	       539 ns/op	   1.86 MB/s	       0 B/op	       0 allocs/op
BenchmarkSessionWriteMessageAsyncRead16-8             	 2109264	       572 ns/op	  27.99 MB/s	       2 B/op	       0 allocs/op
BenchmarkSessionWriteMessageAsyncRead1024-8           	  480385	      2404 ns/op	 425.87 MB/s	      15 B/op	       0 allocs/op
BenchmarkSessionWriteMessageAsyncRead32000-8          	   30163	     39131 ns/op	 817.76 MB/s	     162 B/op	       5 allocs/op
BenchmarkSessionWriteMessageAsyncRead64000-8          	   15435	     77898 ns/op	 821.59 MB/s	     317 B/op	      10 allocs/op

This package is designed to be asynchronous, so basically Write is an stupid wrapper around code of WriteMessageAsync. To get more throughput it merges all your messages collected in 50 microseconds into a one, sends, and then splits them back. It allows to reduce amount of syscalls and other overheads. So to achieve like 1.86MiB/s on 1-byte messages you need to send a lot of them asynchronously (from each other), so they will be merged while sending/receiving through the backend connection.

Also this 800MiB/s is more about the localhost-case. And more realistic network case (if we have MTU ~= 1400) is:

BenchmarkSessionWriteMessageAsyncRead1300_max1400-8   	  117862	     10277 ns/op	 126.49 MB/s	     267 B/op	      10 allocs/op

Security design

Key exchange

The remote side is authenticated by a ED25519 signature (of the key exchange message).

Key exchange is performed via ECDH with X25519. If a PSK is set, then it is PSK concatenated with a constant salt-value, hashed with blake3.Sum256 and sha3.Sum256 and used to XOR the (exchanged) key.

The resulting value is used as the encryption key for XChaCha20. This key is called cipherKey within the code.

The key (received via ECDH) is updated every minute. So in turn the cipherKey is updated every minute as well.


A SessionID is exchanged by the very first key-exchange messages. SessionID is a combination of UnixNano (of when the Session was initialized) and random 64-bit integer.

Also each packet starts with an unique (for a session) plain-text PacketID (actually if PSK is set then PacketID encrypted with a key derived as a hash of a salted PSK).

The combination of PacketID and SessionID is used as IV/NONCE for XChaCha20 and cipherKey is used as the key.

Worth to mention that PacketID is intended to be unique only within a Session. So it just starts with zero and then increases by 1 for each next message. Therefore if the system clock is broken then uniqueness of NONCE is guaranteed by 64-bit random value of SessionID.

Message authentication

Message authentication is done using Poly1305. As key for Poly1305 used a blake3.Sum256 hash of:

PacketID is supposed to be increasing only. Received PacketID are remembered in a limited window of values. If it was received a packet with the same PacketID (as it already was) or with a lesser PackerID (than the minimal possible value in the window) then the packet is just ignored.

Session states

A successful session with the default settings goes through states/phases/stages:

  • Initialization
  • Key exchanging
  • Negotiation
  • Established
  • Closing
  • Closed


This is the stage where all the options are parsed and all the required goroutines are being initialized.

After that *Session will be switched to the "Key Exchanging" state.

Key exchanging

At this stage both parties (the local one and the remote one) are exchanging with ECDH public keys to get a symmetrical shared key (see "Security Design").

Also if a remote identity is set then we verify if it matches, and ignores any key-exchange messages with any other ED25519 public keys (don't confuse with ECDH public key): ED25519 keypairs are static for each party (and usually pre-defined), while ECDH keypairs are generated for each key exchange.

Also each key-exchanging key is verified by the public key (passed with the message).

With the default settings, each party also sends acknowledgement messages to verify if the messages was received and percieved. And (with the default settings) each party waits for a acknowledgment message from the remote side (see also SessionOptions.AnswersMode).

If everything is successful here then the *Session goes to the "Negotiation" phase. But the key exchanging process is still periodically performed in background.


At this stage we try to determine which size of packets the underlying io.Writer can handle. So we try to send packets of 3 different sizes and look which of them will be able to make a round trip. Then repeat the procedure in a shorter interval. And so on up to 4 times.

This behavior could be enabled or disabled through SessionOptions.NegotiatorOptions.Enable.

When this procedure will be finished (or if it is disabled), then the *Session is switched to the state "Established".


This is the state in which the *Session is operating normally, so you may send and receive messages through it. And messages attempted to be sent before reaching this stage will be sent as soon as *Session will reach this stage.

Closing / Closed

Closing is a transitional state before becoming Closed. If state Closed is reached it means the session is dead and nothing will ever happen to it anymore.


  • support of fragmented/merged (by backend) traffic.
  • check keyCreatedAt
  • error if key hasn't changed
  • verify TS difference sanity
  • don't use Async for sync-writes.
  • route messenger-related errors to the messenger's handler.
  • more comments (in the code)
  • consider notewakeup instead of Cond.Wait

I'm not sure if we need

  • download key-files by URLs
Calculate SHA256 checksums of objects on Amazon S3.

s3sha256sum is a small program that calculates SHA256 checksums of objects stored on Amazon S3. Use it to verify the integrity of your objects. If the

Stefan Sundin 4 Dec 5, 2021
Peer-to-peer encrypted message exchange

Constellation Constellation is a self-managing, peer-to-peer system in which each node: Hosts a number of NaCl (Curve25519) public/private key pairs.

ConsenSys Software 370 Dec 4, 2021
Map ssh-ed25519 keys into x25519 keys

ssh-x22519 ========== The twisted Edwards curve used for ed25519 signatures is birationally equivalent to the Montgomery curve used for x25519: it is

Chris Webb 1 Oct 30, 2021
A Go Implementation of ECDH-PSI

A Go Implementation of ECDH-PSI This is a Go implementation of elliptic curve diffie hellman private set intersection (ECDH-PSI) with only standard li

Zilin Zhu 1 Dec 16, 2021
Simple, fast and safe cross-platform linear binary stream communication protocol. AES key exchange based on ecc secp256k1

FFAX Protocol 2 dev 简体中文 Welcome to FFAX Protocol v2 Quick start go get func example() { listener, err := net.Listen("tcp",

Realfax Messenger 60 Jan 4, 2022
Easy to use encryption library for Go

encryptedbox EncryptedBox is an easy to use module for Go that can encrypt or sign any type of data. It is especially useful when you must serialize y

Jesse Swidler 18 Oct 26, 2021
TTAK.KO-12.0223 Lightweight Encryption Algorithm with Galois/Counter Mode (LEA-GCM)

LEACrypt The Lightweight Encryption Algorithm (also known as LEA) is a 128-bit block cipher developed by South Korea in 2013 to provide confidentialit

Pedro F. Albanese 0 Dec 28, 2021
A dead simple tool to sign files and verify digital signatures.

minisign minisign is a dead simple tool to sign files and verify signatures. $ minisign -G

Andreas Auernhammer 51 Dec 29, 2021
A super easy file encryption utility written in go and under 800kb

filecrypt A super easy to use file encryption utility written in golang ⚠ Help Wanted on porting filecrypt to other programing languages NOTE: if you

Flew Software 75 Nov 5, 2021
Ethereum 2.0 node multiplexer between consensus and execution

The Minority Client Run the minority client! ~Danny Ryan and/or Tim Beiko As of writing, Ethereum has multiple client implementations, but Geth / go-e

Péter Szilágyi 59 Dec 21, 2021
A drop-in replacement to any Writer type, which also calculates a hash using the provided hash type.

writehasher A drop-in replacement to any Writer type, which also calculates a hash using the provided hash type. Example package main import ( "fmt"

Max 0 Jan 10, 2022
Go Encrypt! Is a simple command-line encryption and decryption application using AES-256 GCM.

Go Encrypt! Go Encrypt! is a command-line application used to easily encrypt and decrypt files with the AES-256 GCM encryption algorithm. Usage Usage

Peter Georgas 0 Jan 5, 2022
Trader is a framework that automated cryptocurrency exchange with strategy

A framework that automated cryptocurrency exchange with strategy

long2ice 59 Dec 10, 2021
Diffie Hellman Exchange - A Generic Transport Upgrader Implementation

Diffie Hellman Exchange A simple but fastidious attempt to write a diffie-hellman key exchange utility that could be used as transport upgraders in di

null 0 Dec 28, 2021
A simple, semantic and developer-friendly golang package for encoding&decoding and encryption&decryption

A simple, semantic and developer-friendly golang package for encoding&decoding and encryption&decryption

null 69 Jan 6, 2022
A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability.

A simple, modern and secure encryption tool (and Go library) with small explicit keys, no config options, and UNIX-style composability.

Filippo Valsorda 9.7k Jan 15, 2022
Uses Google's classic diff-match-patch algorithm to compare two files, sending the color highlighted output to *testing.T for use when testing expected versus actual results.

Compare-files uses Google's classic diff-match-patch algorithm to compare two files. It sends the color highlighted output to *testing.T for use when

Read Write Pro 0 Dec 30, 2021
Public key derivator for ECDSA (without knowledge of the private key)

A proof of concept of a public key derivation for ECDSA (without knowledge of the private key) It is a demonstration of how to implement a simple key

null 1 Dec 16, 2021
PortScanner - 多线程端口扫描器,支持TCP、UDP、ICMP协议的多线程扫描

Introduction 端口扫描器,支持TCP 、UDP 、ICMP协议的多线程扫描 架构 Vue Golang/gin demo Scan UDP Scan

Soreat_u 5 Dec 31, 2021