saltpack

README

Saltpack

See saltpack.org for more details.

This github.com/keys-pub/keys/saltpack package allows you to encrypt/decrypt, sign/verify using Saltpack.

Examples

• Encrypt + Decrypt
• Sign + Verify

Documentation

Overview

Package saltpack integrates keys with Saltpack (saltpack.org).

Index

• func Decrypt(b []byte, armored bool, kr Keyring) ([]byte, *keys.X25519PublicKey, error)
• func Encrypt(b []byte, armored bool, sender *keys.X25519Key, recipients ...keys.ID) ([]byte, error)
• func NewDecryptStream(r io.Reader, armored bool, kr Keyring) (io.Reader, *keys.X25519PublicKey, error)
• func NewEncryptStream(w io.Writer, armored bool, sender *keys.X25519Key, recipients ...keys.ID) (io.WriteCloser, error)
• func NewSignStream(w io.Writer, armored bool, detached bool, key *keys.EdX25519Key) (io.WriteCloser, error)
• func NewSigncryptOpenStream(r io.Reader, armored bool, kr Keyring) (io.Reader, *keys.EdX25519PublicKey, error)
• func NewSigncryptStream(w io.Writer, armored bool, sender *keys.EdX25519Key, recipients ...keys.ID) (io.WriteCloser, error)
• func NewVerifyStream(r io.Reader) (io.Reader, keys.ID, error)
• func SetLogger(l Logger)
• func Sign(b []byte, armored bool, key *keys.EdX25519Key) ([]byte, error)
• func SignDetached(b []byte, armored bool, key *keys.EdX25519Key) ([]byte, error)
• func SignFile(in string, out string, key *keys.EdX25519Key, armored bool, detached bool) error
• func Signcrypt(b []byte, armored bool, sender *keys.EdX25519Key, recipients ...keys.ID) ([]byte, error)
• func SigncryptOpen(b []byte, armored bool, kr Keyring) ([]byte, *keys.EdX25519PublicKey, error)
• func StripBefore(message string) string
• func Verify(b []byte) ([]byte, keys.ID, error)
• func VerifyDetached(sig []byte, b []byte) (keys.ID, error)
• func VerifyDetachedReader(sig []byte, r io.Reader) (keys.ID, error)
• func VerifyFile(in string, out string) (keys.ID, error)
• func VerifyFileDetached(sig []byte, path string) (keys.ID, error)
• type ContextLogger
  • func NewContextLogger(lev LogLevel) ContextLogger
• type Encoding
  • func NewReader(r io.Reader, kr Keyring) (out io.Reader, key keys.Key, enc Encoding, err error)
  • func Open(b []byte, kr Keyring) (out []byte, key keys.Key, enc Encoding, err error)
• type Keyring
  • func NewKeyring(keys ...keys.Key) Keyring
• type LogLevel
• type Logger
  • func NewLogger(lev LogLevel) Logger

Examples

• Decrypt
• Encrypt
• Sign
• SignDetached
• Verify

Functions

func Decrypt

func Decrypt(b []byte, armored bool, kr Keyring) ([]byte, *keys.X25519PublicKey, error)

Decrypt bytes. If there was a sender, will return the X25519 public key.

Example

package main

import (
	"fmt"
	"log"

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

func main() {
	// Message from ExampleEncrypt
	aliceID := keys.ID("kbx17jhqvdrgdyruyseuaat0rerj7ep4n63n4klufzxtzmk9p3d944gs4fg39g")
	encrypted := []byte(`BEGIN SALTPACK ENCRYPTED MESSAGE.
	kcJn5brvybfNjz6 D5ll2Nk0YiiGFCz I2xgcLXuPzYNBe3 OboFDA8Gh0TxosH yo82IRf2OZzteqO
	GaPWlm7t0lC0M0U vNnOvsussLf1nMw Oo1Llf9oAbA7qxa GjupUEWnTgyjjUn GKb3WvtjSgRsJS2
	Y92GMEx8cHvbGrJ zvLGlbqAhEIDNZ2 SE15aoV6ahVxeVH 1inHyghv3H1oTAC K86mBl4fg9FY1QK
	4n0gLOmSHbD8UYH V3HAPS0yaBC4xJB g3y04Xcqiij36Nb WmJgvSFdGugXd7O yfU.
	END SALTPACK ENCRYPTED MESSAGE.
	`)

	// Bob is keys.ID("kbx18x22l7nemmxcj76f9l3aaflc5487lp5u5q778gpe3t3wzhlqvu8qxa9z07")
	key := `BEGIN X25519 KEY MESSAGE.
	umCRo9iHIudLWoz 4Ugt0hUXQVJ7lhV p7A9mb3kOTg6PeV fhqetAc9ZOUjagi
	91gENEkp0xfjF2E Tyakwe90kzo1FNT gRacWRL5B59strN OoZYHQooqvlMKM.
	END X25519 KEY MESSAGE.`
	bob, err := keys.DecodeSaltpackKey(key, "", true)
	if err != nil {
		log.Fatal(err)
	}

	// Bob decrypts
	out, sender, err := saltpack.Decrypt(encrypted, true, saltpack.NewKeyring(bob))
	if err != nil {
		log.Fatal(err)
	}

	if sender != nil && sender.ID() == aliceID {
		fmt.Printf("signer is alice\n")
	}
	fmt.Printf("%s\n", string(out))

}

Output:

signer is alice
hi bob

func Encrypt

func Encrypt(b []byte, armored bool, sender *keys.X25519Key, recipients ...keys.ID) ([]byte, error)

Encrypt to recipients. Sender can be nil, if you want it to be anonymous. https://saltpack.org/encryption-format-v2

Example

package main

import (
	"fmt"
	"log"

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

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

	message := []byte("hi bob")

	// Encrypt from alice to bob
	encrypted, err := saltpack.Encrypt(message, true, alice, bob.ID())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%d", len(encrypted))
}

Output:

375

func NewDecryptStream

func NewDecryptStream(r io.Reader, armored bool, kr Keyring) (io.Reader, *keys.X25519PublicKey, error)

NewDecryptStream creates a decrypt stream. If there was a sender, will return a X25519 key ID.

func NewEncryptStream

func NewEncryptStream(w io.Writer, armored bool, sender *keys.X25519Key, recipients ...keys.ID) (io.WriteCloser, error)

NewEncryptStream creates an encrypted armored io.WriteCloser. Sender can be nil, if you want it to be anonymous.

func NewSignStream

func NewSignStream(w io.Writer, armored bool, detached bool, key *keys.EdX25519Key) (io.WriteCloser, error)

NewSignStream ...

func NewSigncryptOpenStream

func NewSigncryptOpenStream(r io.Reader, armored bool, kr Keyring) (io.Reader, *keys.EdX25519PublicKey, error)

NewSigncryptOpenStream creates a signcrypt open stream.

func NewSigncryptStream

func NewSigncryptStream(w io.Writer, armored bool, sender *keys.EdX25519Key, recipients ...keys.ID) (io.WriteCloser, error)

NewSigncryptStream creates a signcrypt stream.

func NewVerifyStream

func NewVerifyStream(r io.Reader) (io.Reader, keys.ID, error)

NewVerifyStream ...

func SetLogger

func SetLogger(l Logger)

SetLogger sets logger for the package.

func Sign

func Sign(b []byte, armored bool, key *keys.EdX25519Key) ([]byte, error)

Sign ...

Example

package main

import (
	"fmt"
	"log"

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

func main() {
	alice := keys.GenerateEdX25519Key()

	message := []byte("hi from alice")

	sig, err := saltpack.Sign(message, true, alice)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", alice.ID())
	fmt.Printf("%s\n", sig)
}

func SignDetached

func SignDetached(b []byte, armored bool, key *keys.EdX25519Key) ([]byte, error)

SignDetached ...

Example

package main

import (
	"fmt"
	"log"

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

func main() {
	alice := keys.GenerateEdX25519Key()

	message := []byte("hi from alice")

	sig, err := saltpack.SignDetached(message, true, alice)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s", sig)
}

func SignFile

func SignFile(in string, out string, key *keys.EdX25519Key, armored bool, detached bool) error

SignFile signs a file.

func Signcrypt

func Signcrypt(b []byte, armored bool, sender *keys.EdX25519Key, recipients ...keys.ID) ([]byte, error)

Signcrypt to recipients. https://saltpack.org/signcryption-format

func SigncryptOpen

func SigncryptOpen(b []byte, armored bool, kr Keyring) ([]byte, *keys.EdX25519PublicKey, error)

SigncryptOpen ...

func StripBefore

func StripBefore(message string) string

StripBefore removes text before BEGIN.

func Verify

func Verify(b []byte) ([]byte, keys.ID, error)

Verify ...

Example

package main

import (
	"fmt"
	"log"

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

func main() {
	aliceID := keys.ID("kex1w2jep8dkr2s0g9kx5g6xe3387jslnlj08yactvn8xdtrx4cnypjq9rpnux")
	signed := []byte(`BEGIN SALTPACK SIGNED MESSAGE. 
	kXR7VktZdyH7rvq v5wcIkHbs7mPCSd NhKLR9E0K47y29T QkuYinHym6EfZwL 
	1TwgxI3RQ52fHg5 1FzmLOMghcYLcV7 i0l0ovabGhxGrEl z7WuI4O3xMU5saq 
	U28RqUnKNroATPO 5rn2YyQcut2SeMn lXJBlDqRv9WyxjG M0PcKvsAsvmid1m 
	cqA4TCjz5V9VpuO zuIQ55lRQLeP5kU aWFxq5Nl8WsPqlR RdX86OuTbaKUvKI 
	wdNd6ISacrT0I82 qZ71sc7sTxiMxoI P43uCGaAZZ3Ab62 vR8N6WQPE8. 
	END SALTPACK SIGNED MESSAGE.`)

	out, signer, err := saltpack.Verify(signed)
	if err != nil {
		log.Fatal(err)
	}
	if signer == aliceID {
		fmt.Printf("signer is alice\n")
	}
	fmt.Printf("%s\n", string(out))
}

Output:

signer is alice
hi from alice

func VerifyDetached

func VerifyDetached(sig []byte, b []byte) (keys.ID, error)

VerifyDetached ...

func VerifyDetachedReader

func VerifyDetachedReader(sig []byte, r io.Reader) (keys.ID, error)

VerifyDetachedReader ...

func VerifyFile

func VerifyFile(in string, out string) (keys.ID, error)

VerifyFile outputs verified file from in path.

func VerifyFileDetached

func VerifyFileDetached(sig []byte, path string) (keys.ID, error)

VerifyFileDetached verifies file at path with signature.

Types

type ContextLogger

type ContextLogger interface {
	Debugf(ctx context.Context, format string, args ...interface{})
	Infof(ctx context.Context, format string, args ...interface{})
	Warningf(ctx context.Context, format string, args ...interface{})
	Errorf(ctx context.Context, format string, args ...interface{})
}

ContextLogger interface used in this package with request context.

func NewContextLogger

func NewContextLogger(lev LogLevel) ContextLogger

NewContextLogger ...

type Encoding

type Encoding string

Encoding for saltpack (armored vs binary, encrypt vs signcrypt).

const (
	// UnknownEncoding is unknown.
	UnknownEncoding Encoding = ""
	// EncryptEncoding used saltpack.Encrypt
	EncryptEncoding Encoding = "encrypt"
	// SigncryptEncoding used saltpack.Signcrypt
	SigncryptEncoding Encoding = "signcrypt"
	// SignEncoding used saltpack.Sign
	SignEncoding Encoding = "sign"
)

func NewReader

func NewReader(r io.Reader, kr Keyring) (out io.Reader, key keys.Key, enc Encoding, err error)

NewReader creates io.Reader for decryption after trying to detect the encoding. We peek up to 512 bytes from the reader, detect the encoding and return that stream.

func Open

func Open(b []byte, kr Keyring) (out []byte, key keys.Key, enc Encoding, err error)

Open decrypts bytes after attempting to auto detect the encoding.

type Keyring

type Keyring interface {
	X25519Keys() ([]*keys.X25519Key, error)
}

Keyring for Saltpack keys.

func NewKeyring

func NewKeyring(keys ...keys.Key) Keyring

NewKeyring creates keyring for keys.

type LogLevel

type LogLevel int

LogLevel ...

const (
	// DebugLevel ...
	DebugLevel LogLevel = 3
	// InfoLevel ...
	InfoLevel LogLevel = 2
	// WarnLevel ...
	WarnLevel LogLevel = 1
	// ErrLevel ...
	ErrLevel LogLevel = 0
)

type Logger

type Logger interface {
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Warningf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

Logger interface used in this package.

func NewLogger

func NewLogger(lev LogLevel) Logger

NewLogger ...