noise

README

Noise

This package helps setup a Noise handshake using X25519 keys.

For more details visit keys.pub.

The default cipher suite used is: Curve25519 ECDH, ChaCha20-Poly1305 AEAD, BLAKE2b hash.

The handshake uses the KK pattern:

• K = Static key for initiator Known to responder
• K = Static key for responder Known to initiator

One of the Noise participants should be the initiator.

The order of the handshake writes/reads should be:

• (1) Initiator: Write
• (2) Responder: Read
• (3) Initiator: Read
• (4) Responder: Write

When the handshake is complete, use the Cipher to Encrypt/Decrypt.

See noisprotocol.org for more info.

The following example completes a handshake using two X25519 keys (Alice and Bob), and uses the cipher to encrypt and decrypt.

import (
    "github.com/keys-pub/keys"
    "github.com/keys-pub/keys/noise"
)

...

alice := keys.GenerateX25519Key()
bob := keys.GenerateX25519Key()

na, err := noise.NewHandshake(alice, bob.PublicKey(), true)
if err != nil {
    log.Fatal(err)
}

nb, err := noise.NewHandshake(bob, alice.PublicKey(), false)
if err != nil {
    log.Fatal(err)
}

// -> s
// <- s
ha, err := na.Write(nil)
if err != nil {
    log.Fatal(err)
}
if _, err := nb.Read(ha); err != nil {
    log.Fatal(err)
}
// -> e, es, ss
// <- e, ee, se
hb, err := nb.Write(nil)
if err != nil {
    log.Fatal(err)
}
if _, err := na.Read(hb); err != nil {
    log.Fatal(err)
}

// transport I -> R
ca, err := na.Cipher()
if err != nil {
    log.Fatal(err)
}
encrypted, err := ca.Encrypt(nil, nil, []byte("hello"))
if err != nil {
    log.Fatal(err)
}

cb, err := nb.Cipher()
if err != nil {
    log.Fatal(err)
}
decrypted, err := cb.Decrypt(nil, nil, encrypted)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("%s", string(decrypted))
// Output: hello

Documentation

Overview

Package noise integrates keys with the Noise protocol.

Index

• type Cipher
• type Handshake
  • func NewHandshake(sender *keys.X25519Key, recipient *keys.X25519PublicKey, initiator bool) (*Handshake, error)
  • func (n *Handshake) Cipher() (Cipher, error)
  • func (n *Handshake) Complete() bool
  • func (n *Handshake) Read(b []byte) ([]byte, error)
  • func (n *Handshake) Write(payload []byte) ([]byte, error)

Examples

• NewHandshake

Types

type Cipher

type Cipher interface {
	Encrypt(out, ad, plaintext []byte) ([]byte, error)
	Decrypt(out, ad, ciphertext []byte) ([]byte, error)
}

Cipher provides symmetric encryption and decryption after a successful handshake.

type Handshake

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

Noise protocol for keys.pub. See http://www.noiseprotocol.org/.

func NewHandshake

func NewHandshake(sender *keys.X25519Key, recipient *keys.X25519PublicKey, initiator bool) (*Handshake, error)

NewHandshake returns a Handshake for X25519Key sender and recipient.

The cipher suite used is: Curve25519 ECDH, ChaCha20-Poly1305 AEAD, BLAKE2b hash.

The handshake uses the KK pattern: K = Static key for initiator Known to responder K = Static key for responder Known to initiator

One of the Noise participants should be the initiator.

The order of the handshake writes/reads should be: (1) Initiator: Write (2) Responder: Read (3) Initiator: Read (4) Responder: Write

When the handshake is complete, use the Cipher to Encrypt/Decrypt.

Example

package main

import (
	"fmt"
	"log"

	"github.com/keys-pub/keys"
	"github.com/keys-pub/keys/noise"
)

func main() {
	alice := keys.GenerateX25519Key()
	bob := keys.GenerateX25519Key()

	na, err := noise.NewHandshake(alice, bob.PublicKey(), true)
	if err != nil {
		log.Fatal(err)
	}

	nb, err := noise.NewHandshake(bob, alice.PublicKey(), false)
	if err != nil {
		log.Fatal(err)
	}

	// -> s
	// <- s
	ha, err := na.Write(nil)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := nb.Read(ha); err != nil {
		log.Fatal(err)
	}
	// -> e, es, ss
	// <- e, ee, se
	hb, err := nb.Write(nil)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := na.Read(hb); err != nil {
		log.Fatal(err)
	}

	// transport I -> R
	ca, err := na.Cipher()
	if err != nil {
		log.Fatal(err)
	}
	encrypted, err := ca.Encrypt(nil, nil, []byte("hello"))
	if err != nil {
		log.Fatal(err)
	}

	cb, err := nb.Cipher()
	if err != nil {
		log.Fatal(err)
	}
	decrypted, err := cb.Decrypt(nil, nil, encrypted)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s", string(decrypted))
}

Output:

hello

func (*Handshake) Cipher

func (n *Handshake) Cipher() (Cipher, error)

Cipher provides symmetric encryption and decryption after a successful handshake.

func (*Handshake) Complete

func (n *Handshake) Complete() bool

Complete returns true if handshake is complete and Encrypt/Decrypt are available.

func (*Handshake) Read

func (n *Handshake) Read(b []byte) ([]byte, error)

Read performs handshake read, returning optional payload if it was included in the Write, as the pattern allows zero-RTT encryption, meaning the initiator can encrypt the first handshake payload.

The order of the handshake writes/reads should be: (1) Initiator: Write (2) Responder: Read (3) Initiator: Read (4) Responder: Write

func (*Handshake) Write

func (n *Handshake) Write(payload []byte) ([]byte, error)

Write performs handshake write. You can include optional payload bytes, as the pattern allows zero-RTT encryption, meaning the initiator can encrypt the first handshake payload.

The order of the handshake writes/reads should be: (1) Initiator: Write (2) Responder: Read (3) Initiator: Read (4) Responder: Write