whisper

Documentation

Index

• Constants
• Variables
• 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 ExtractRemotePublicKey(p string) (string, bool)
• func IsPassphraseRight(prv PrivateKey) (bool, error)
• func ReadKey(unixPath string) ([]byte, error)
• func SSHDir() (string, error)
• type AgentClient
  • func NewAgentClient(addr string) AgentClient
• 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) IsDecryption() bool
  • func (c Config) PubKeyHashList() (bool, [][]byte, error)
• type Meta
  • func DecodeMeta(in io.Reader) (*Meta, error)
  • func PeakMeta(in io.ReadCloser) (*Meta, io.ReadCloser, error)
  • func (m *Meta) FindSSHPrivateKey() (string, 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 FetchPublicKey(location string) (*PublicKey, error)
  • func PublicKeyFromMeta(m string) PublicKey
  • func (k PublicKey) Meta() string
  • func (k PublicKey) Select() ([]byte, error)
• type Whisper
  • func New(conf Config) *Whisper
  • func (w *Whisper) Decoder(in io.Reader) (io.ReadCloser, error)
  • func (w *Whisper) Encoder(out io.Writer) (io.WriteCloser, error)
  • func (w *Whisper) Handle(input io.ReadCloser, output io.WriteCloser) error

Examples

• New

Constants

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

Variables

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

var ErrPrvKeyNotFound = errors.New("private key not found")

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 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 ExtractRemotePublicKey

func ExtractRemotePublicKey(p string) (string, bool)

func IsPassphraseRight

func IsPassphraseRight(prv PrivateKey) (bool, error)

func ReadKey

func ReadKey(unixPath string) ([]byte, error)

func SSHDir

func SSHDir() (string, error)

Types

type AgentClient

type AgentClient interface {
	Whisper(conf Config, in io.Reader, out io.Writer) error
	IsPassphraseRight(prv PrivateKey) (bool, error)
	IsServerRunning(version string) (bool, error)
	ClearCache() error
}

func NewAgentClient

func NewAgentClient(addr string) AgentClient

type AgentReq

type AgentReq struct {
	Version         string
	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.
	// If the list is empty, it will be a decryption process.
	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) IsDecryption

func (c Config) IsDecryption() bool

func (Config) PubKeyHashList

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

type Meta

type Meta struct {
	Gzip           bool
	Sign           bool
	LongPubKeyHash bool

	Sender *PublicKey

	// The key is the hash of the recipient's public key, value is the index of the recipient in the key list.
	Recipients map[string]int
}

func DecodeMeta

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

DecodeMeta decodes the meta from the whisper file.

func PeakMeta

func PeakMeta(in io.ReadCloser) (*Meta, io.ReadCloser, error)

PeakMeta read the meta data from the input stream, and return the unread input stream.

func (*Meta) FindSSHPrivateKey

func (m *Meta) FindSSHPrivateKey() (string, error)

FindSSHPrivateKey find the private key that matches the recipients' public key in the ~/.ssh folder.

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 FetchPublicKey

func FetchPublicKey(location string) (*PublicKey, error)

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
}

Whisper is a data encryption and decryption file format. The whisper file extension is ".wsp".

func New

func New(conf Config) *Whisper

New encoder and decoder pair. The encoding process:

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

The sign, gzip, base64 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!

func (*Whisper) Decoder

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

Decoder decrypt data stream from the in as whisper file format.

func (*Whisper) Encoder

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

Encoder encrypt data stream to the out as whisper file format.

func (*Whisper) Handle

func (w *Whisper) Handle(input io.ReadCloser, output io.WriteCloser) error