whisper

Documentation

Index

• Constants
• Variables
• func CallAgent(addr string, req AgentReq, in io.Reader, out io.Writer) error
• func ClearCache(addr string) error
• func Decode(data []byte, conf Config) ([]byte, error)
• func DecodeString(data string, conf Config) (string, error)
• func Encode(data []byte, conf Config) ([]byte, error)
• func EncodeString(data string, conf Config) (string, error)
• func IsAgentRunning(addr, version string) (bool, error)
• func IsPassphraseRight(addr string, prv PrivateKey) (bool, error)
• func New(conf Config) piper.EncodeDecoder
• type AgentReq
• type AgentRes
• type AgentServer
  • func NewAgentServer() *AgentServer
  • func (a *AgentServer) Handle(s io.ReadWriteCloser) error
  • func (a *AgentServer) Listen(l net.Listener)
  • func (a *AgentServer) Serve(addr string)
• type Config
  • func (c Config) EncodeMeta(out io.Writer) error
  • func (c Config) PubKeyHashList() (bool, [][]byte, error)
• type Meta
  • func DecodeMeta(in io.Reader) (*Meta, error)
  • func (m Meta) GetIndex(p PrivateKey) (int, error)
  • func (m Meta) HasPubKey(p PublicKey) (bool, error)
  • func (m Meta) HashSize() int
• type MetaFlag
• type PrivateKey
• type PublicKey
  • func PublicKeyFromMeta(m string) PublicKey
  • func (k PublicKey) Meta() string
  • func (k PublicKey) Select() ([]byte, error)
• type Whisper
  • func (w *Whisper) Decoder(in io.Reader) (io.ReadCloser, error)
  • func (w *Whisper) Encoder(out io.Writer) (io.WriteCloser, error)

Examples

• New

Constants

const (
	APIVersion    = "v0.3.6"
	FormatVersion = byte(3)
)

Variables

var ErrNoPrivateKey = errors.New("no private key")

var ErrPubKeyNotFound = errors.New("public key not found")

var ErrPubPrvNotMatch = errors.New("public and private key not match")

var ErrVersionMismatch = errors.New("whisper file format version mismatch")

var ErrWrongPublicKey = errors.New("the public key from option -a doesn't belong to the private key")

Functions

func CallAgent

func CallAgent(addr string, req AgentReq, in io.Reader, out io.Writer) error

Return true if the passphrase is correct.

func ClearCache

func ClearCache(addr string) error

func Decode

func Decode(data []byte, conf Config) ([]byte, error)

func DecodeString

func DecodeString(data string, conf Config) (string, error)

func Encode

func Encode(data []byte, conf Config) ([]byte, error)

func EncodeString

func EncodeString(data string, conf Config) (string, error)

func IsAgentRunning

func IsAgentRunning(addr, version string) (bool, error)

func IsPassphraseRight

func IsPassphraseRight(addr string, prv PrivateKey) (bool, error)

func New

func New(conf Config) piper.EncodeDecoder

New encoder and decoder pair. The encoding process:

data -> gzip -> cipher -> sign -> meta

The sign, gzip are optional.

Decoding is the reverse as the encoding. It will still decode the whole data even the signature check fails, it will return secure.ErrSignNotMatch error.

Example

package main

import (
	"fmt"
	"os"
	"path/filepath"

	whisper "github.com/ysmood/whisper/lib"
)

func main() {
	recipient01, recipient01Pub := keyPair("id_ecdsa01", "test")
	recipient02, recipient02Pub := keyPair("id_ecdsa02", "test")

	// Encrypt the message that can be decrypted by both recipient01 and recipient02.
	encrypted, _ := whisper.EncodeString("hello world!", whisper.Config{
		Public: []whisper.PublicKey{recipient01Pub, recipient02Pub},
	})

	decrypted01, _ := whisper.DecodeString(encrypted, whisper.Config{Private: &recipient01})
	decrypted02, _ := whisper.DecodeString(encrypted, whisper.Config{Private: &recipient02})

	fmt.Println(decrypted01, decrypted02)

}

func keyPair(privateKeyName, passphrase string) (whisper.PrivateKey, whisper.PublicKey) {
	prv, err := os.ReadFile(filepath.FromSlash("secure/test_data/" + privateKeyName))
	if err != nil {
		panic(err)
	}

	pub, err := os.ReadFile(filepath.FromSlash("secure/test_data/" + privateKeyName + ".pub"))
	if err != nil {
		panic(err)
	}

	return whisper.PrivateKey{prv, passphrase}, whisper.PublicKey{Data: pub}
}

Output:

hello world! hello world!

Types

type AgentReq

type AgentReq struct {
	Version         string
	Decrypt         bool
	CheckPassphrase bool
	ClearCache      bool

	Config Config
}

type AgentRes

type AgentRes struct {
	Running         bool
	PassphraseRight bool
	WrongPublicKey  bool
}

type AgentServer

type AgentServer struct {
	Logger *slog.Logger
	// contains filtered or unexported fields
}

AgentServer is a tcp server that can be used to avoid inputting the passphrase every time. It will do the encryption and decryption for you, not the agent client. There's no way to get the passphrase from the tcp client, the only way to get the passphrase is to have root permission and dump the os memory. If the server restarts you have to send it to server again.

func NewAgentServer

func NewAgentServer() *AgentServer

func (*AgentServer) Handle

func (a *AgentServer) Handle(s io.ReadWriteCloser) error

func (*AgentServer) Listen

func (a *AgentServer) Listen(l net.Listener)

Serve start a http server to avoid inputting the passphrase every time.

func (*AgentServer) Serve

func (a *AgentServer) Serve(addr string)

Serve start a http server to avoid inputting the passphrase every time.

type Config

type Config struct {
	// Gzip compression level
	GzipLevel int

	// For data decryption and signature signing.
	Private *PrivateKey

	// For signature checking and meta data prefixing.
	Sign *PublicKey

	// For data encryption of different recipients
	Public []PublicKey
}

func (Config) EncodeMeta

func (c Config) EncodeMeta(out io.Writer) error

The meta format is:

[version][flags][sender][key num][key2 hash]...

"version" is the whisper file format version. "flags" about the encoding, such as if gzip, base64 are enabled or not. "sender" is the sender's public key [PublicKey.ID] and [PublicKey.Selector]. "key num" is the num of recipients. "key1 hash" is the hash of the first recipient's public key. "key2 hash" is the hash of the second recipient's public key. ...

func (Config) PubKeyHashList

func (c Config) PubKeyHashList() (bool, [][]byte, error)

type Meta

type Meta struct {
	Gzip           bool
	Sign           bool
	LongPubKeyHash bool

	Sender         *PublicKey
	PubKeyHashList map[string]int
}

func DecodeMeta

func DecodeMeta(in io.Reader) (*Meta, error)

func (Meta) GetIndex

func (m Meta) GetIndex(p PrivateKey) (int, error)

GetIndex returns the index of the encrypted secret that the p can decrypt.

func (Meta) HasPubKey

func (m Meta) HasPubKey(p PublicKey) (bool, error)

func (Meta) HashSize

func (m Meta) HashSize() int

type MetaFlag

type MetaFlag byte

const (
	MetaGzip MetaFlag = 1 << iota
	MetaSign
	MetaLongPubKeyHash // If set, the hash size will be [sha1.Size], or it will be 4 bytes
)

type PrivateKey

type PrivateKey struct {
	Data []byte

	// Passphrase is used to decrypt the [PrivateKey.Data]
	Passphrase string
}

type PublicKey

type PublicKey struct {
	Data []byte

	// A public ID for the public key, it can be a https url or github id.
	ID string

	// Uses to select the specific key in the URL file.
	// The line contains the Selector substring will be selected.
	Selector string
}

func PublicKeyFromMeta

func PublicKeyFromMeta(m string) PublicKey

func (PublicKey) Meta

func (k PublicKey) Meta() string

func (PublicKey) Select

func (k PublicKey) Select() ([]byte, error)

Select the line in Data contains the Selector.

type Whisper

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

func (*Whisper) Decoder

func (w *Whisper) Decoder(in io.Reader) (io.ReadCloser, error)

func (*Whisper) Encoder

func (w *Whisper) Encoder(out io.Writer) (io.WriteCloser, error)