oracle

package module
v1.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 25, 2024 License: MIT Imports: 21 Imported by: 4

README

Oracle

go oracle

Oracle is a go library that provides the following cryptographic functions:

  • generate key-pairs
  • encrypt messages
  • decrypt messages
  • sign messages
  • validate messages

Oracle is the basic object that can perform these functions. It also has the concept of a Peer. An Oracle is to a private key as a Peer is to a public key.

Keys are Curve25519. Messages are encrypted using ChaCha20-Poly1305 AEAD. Perfect forward secrecy is assured by making use of one-time ephemeral keys.

This project is heavily inspired by age, especially with respect to cryptographic design. However, I beleive that Oracle provides the following advantages, making it a better choice in some situations:

  • Simpler API, doing away with unesseary abstractions
  • A simple, standard format for messages (PEM)
  • Package first. Oracle is first and foremost a Go package with a sensible API
  • Do one thing and do it well. The companion binary goracle honours the Linux philosophy by accepting input from stdin and producing output to stdout, unlocking composability.

Oracle also comes with a binary called pemreader that reads PEM files.

Documentation

Index

Constants

View Source 
const GLOBAL_SALT = "oracle/v1"

Variables

View Source 
var (
	ErrNotInitialized = errors.New("oracle has not been initialized")
	ErrInvalidConfig  = errors.New("invalid config")
)
View Source 
var ErrKeysAlreadyExist = errors.New("crypto keys already exists")
View Source 
var ErrNoEphemeralKey = errors.New("no ephemeral key")
View Source 
var ErrNotFound = errors.New("not found")
View Source 
var ErrPeerAlreadyAdded = errors.New("Peer already added")
View Source 
var UniversalNonce []byte = make([]byte, chacha20poly1305.NonceSize)
View Source 
var ZeroPrivateKey *ecdh.PrivateKey = new(ecdh.PrivateKey)
View Source 
var ZeroPublicKey *ecdh.PublicKey = new(ecdh.PublicKey)

Functions

This section is empty.

Types

type BunchOfZeros added in v1.3.0 

type BunchOfZeros struct{}

This is a deterministic io.Reader for fake randomness.

func (*BunchOfZeros) Read added in v1.3.0 

func (dr *BunchOfZeros) Read(p []byte) (int, error)

type CipherText 

type CipherText struct {
	Type               string            `json:"type" ion:"type"`
	Headers            map[string]string `json:"headers" ion:"headers"`
	AdditionalData     []byte            `json:"aad" ion:"aad"`
	CipherTextData     []byte            `json:"ciphertext" ion:"ciphertext"`
	Signature          []byte            `json:"signature" ion:"signature"`
	Nonce              []byte            `json:"nonce" ion:"nonce"`
	EphemeralPublicKey []byte            `json:"ephpub" ion:"ephpub"`
	// contains filtered or unexported fields
}

CipherText includes payload and metadata for receiving and decrypting

func (*CipherText) Clone added in v0.1.0 

func (c1 *CipherText) Clone(c2 *CipherText)

func (*CipherText) Digest added in v1.4.2 

func (ct *CipherText) Digest() ([]byte, error)

TODO: is this enough? Is there a compelling reason to include or demand other fields here? In other words, what constitutes valid digesteable CipherText?

func (*CipherText) From added in v0.1.0 

func (ct *CipherText) From(pt *PlainText)

create CipherText from PlainText This does _not_ peform encryption. you must handle PlainTextData and CipherTextData fields seperately.

func (*CipherText) MarshalIon added in v0.1.0 

func (ct *CipherText) MarshalIon() ([]byte, error)

func (*CipherText) MarshalPEM 

func (ct *CipherText) MarshalPEM() ([]byte, error)

func (*CipherText) UnmarshalIon added in v0.1.0 

func (ct *CipherText) UnmarshalIon(bin []byte) error

func (*CipherText) UnmarshalPEM 

func (ct *CipherText) UnmarshalPEM(data []byte) error

type Config 

type Config struct {
	Self  SelfConfig            `json:"self"`
	Peers map[string]PeerConfig `json:"peers"`
}
var ZeroConf Config

func ConfigFrom added in v0.1.2 

func ConfigFrom(r io.Reader) (Config, error)

func (Config) String added in v0.1.2 

func (c Config) String() string

func (Config) Valid added in v0.1.2 

func (c Config) Valid() bool

type Oracle 

type Oracle struct {
	EncryptionPublicKey *ecdh.PublicKey

	SigningPublicKey ed25519.PublicKey

	Handle io.ReadWriter // usually a file handle
	// contains filtered or unexported fields
}

func From 

func From(r io.ReadWriter) (*Oracle, error)

load an Oracle from a file or some other io.Reader

func FromFile added in v0.1.0 

func FromFile(path string) (*Oracle, error)

func New 

func New(rand io.Reader) *Oracle

create a new Oracle with new key-pairs.

func (*Oracle) AddPeer 

func (o *Oracle) AddPeer(p Peer) error

Make an Oracle aware of a Peer. so it can encrypt messages or validate signatures using it's nickname. If a peer is added, that implies we trust it (ie: we have validated it's signature).

func (*Oracle) AsPeer 

func (o *Oracle) AsPeer() Peer

Export the Oracle as a Peer, ensuring only public information is exported

func (*Oracle) Assert added in v1.4.0 

func (o *Oracle) Assert() (*PlainText, error)

func (*Oracle) Bytes added in v1.0.1 

func (o *Oracle) Bytes() []byte

func (*Oracle) Compose added in v0.1.0 

func (o *Oracle) Compose(subject string, body []byte) *PlainText

compose a message intended for a peer

func (*Oracle) Config added in v1.6.1 

func (o *Oracle) Config() Config

func (*Oracle) Decrypt 

func (o *Oracle) Decrypt(ct *CipherText) (*PlainText, error)

decrypt CipherText, returning PlainText

func (*Oracle) Deterministic added in v1.3.0 

func (o *Oracle) Deterministic()

Deterministic sets Oracle to deterministic mode. Good for testing. Bad for privacy.

func (*Oracle) Encrypt 

func (o *Oracle) Encrypt(pt *PlainText, recipient Peer) (*CipherText, error)

encrypt PlaintText, returning CipherText

func (*Oracle) Export 

func (o *Oracle) Export(w io.ReadWriter, andClose bool) error

write an Oracle as a Config to an io.Writer @warning: includes Private key. This should be considered secret

func (*Oracle) GenerateKeys 

func (o *Oracle) GenerateKeys(rand io.Reader) error

func (*Oracle) Load 

func (o *Oracle) Load(r io.Reader) error

func (*Oracle) Nickname 

func (o *Oracle) Nickname() string

an easy way to uniquely identify a Peer. Nickname is derived from PublicKey collisions are technically possible TODO: make nicknames less succeptable to collisions, by making them longer

func (*Oracle) Peer 

func (o *Oracle) Peer(nick string) (Peer, error)

get a Peer from its Nickname

func (*Oracle) Peers 

func (o *Oracle) Peers() map[string]Peer

func (*Oracle) PrivateEncryptionKey added in v0.1.2 

func (o *Oracle) PrivateEncryptionKey() *ecdh.PrivateKey

func (*Oracle) PrivateSigningKey added in v0.1.2 

func (o *Oracle) PrivateSigningKey() ed25519.PrivateKey

func (*Oracle) Public 

func (o *Oracle) Public() crypto.PublicKey

func (*Oracle) PublicEncryptionKey added in v0.1.2 

func (o *Oracle) PublicEncryptionKey() *ecdh.PublicKey

func (*Oracle) PublicKeyAsHex 

func (o *Oracle) PublicKeyAsHex() []byte

func (*Oracle) PublicSigningKey added in v0.1.2 

func (o *Oracle) PublicSigningKey() ed25519.PublicKey

func (*Oracle) Randomness added in v0.1.2 

func (o *Oracle) Randomness() io.Reader

func (*Oracle) Release added in v1.6.1 

func (orc *Oracle) Release() error

func (*Oracle) Save added in v1.3.0 

func (o *Oracle) Save() error

func (*Oracle) Sign 

func (o *Oracle) Sign(pt *PlainText) error

func (*Oracle) Verify 

func (o *Oracle) Verify(pt *PlainText, sender Signer) bool

type Peer 

type Peer [64]byte

32 bytes for the encryption key, 32 for the signing key 

var NoPeer Peer

func NewPeer added in v0.1.1 

func NewPeer(seedSlice []byte) Peer

func PeerFromHex 

func PeerFromHex(hexData []byte) (Peer, error)

func (Peer) Bytes added in v0.1.1 

func (p Peer) Bytes() []byte

func (Peer) Config added in v1.6.1 

func (p Peer) Config() PeerConfig

func (Peer) EncryptionKey added in v0.1.1 

func (p Peer) EncryptionKey() *ecdh.PublicKey

func (Peer) Equal added in v1.4.0 

func (p Peer) Equal(x crypto.PublicKey) bool

func (Peer) MarshalBinary added in v1.4.0 

func (p Peer) MarshalBinary() ([]byte, error)

func (Peer) MarshalHex added in v0.1.1 

func (p Peer) MarshalHex() ([]byte, error)

func (Peer) MarshalJSON added in v1.4.0 

func (p Peer) MarshalJSON() ([]byte, error)

func (Peer) Nickname 

func (p Peer) Nickname() string

func (Peer) SigningKey added in v0.1.1 

func (p Peer) SigningKey() ed25519.PublicKey

func (*Peer) UnmarshalBinary added in v1.4.0 

func (p *Peer) UnmarshalBinary(data []byte) error

func (*Peer) UnmarshalHex added in v0.1.1 

func (p *Peer) UnmarshalHex(data []byte) error

func (*Peer) UnmarshalJSON added in v1.4.0 

func (p *Peer) UnmarshalJSON(data []byte) error

type PeerConfig added in v1.6.1 

type PeerConfig struct {
	Nickname  string `json:"nick"`
	PublicKey string `json:"pub"`
}

type PlainText 

type PlainText struct {
	Type               string            `json:"type" ion:"type"`
	Headers            map[string]string `json:"headers" ion:"headers"`
	AdditionalData     []byte            `json:"aad" ion:"aad"`
	PlainTextData      []byte            `json:"plaintext" ion:"plaintext"`
	Signature          []byte            `json:"signature" ion:"signature"`
	Nonce              []byte            `json:"nonce" ion:"nonce"`
	EphemeralPublicKey []byte            `json:"ephpub" ion:"ephpub"`
	// contains filtered or unexported fields
}

PlainText includes payload and metadata for encrypting and sending

func (*PlainText) CipherText added in v0.1.0 

func (pt *PlainText) CipherText() ([]byte, error)

func (*PlainText) Clone added in v0.1.0 

func (pt *PlainText) Clone(p2 *PlainText)

func (*PlainText) Digest added in v0.1.0 

func (pt *PlainText) Digest() ([]byte, error)

func (*PlainText) From added in v0.1.0 

func (pt *PlainText) From(ct *CipherText)

func (*PlainText) MarshalIon added in v0.1.0 

func (pt *PlainText) MarshalIon() ([]byte, error)

func (*PlainText) MarshalPEM added in v0.1.0 

func (pt *PlainText) MarshalPEM() ([]byte, error)

func (*PlainText) PlainText added in v0.1.0 

func (pt *PlainText) PlainText() ([]byte, error)

func (*PlainText) Sign added in v0.1.0 

func (pt *PlainText) Sign(randy io.Reader, priv ed25519.PrivateKey) error

func (*PlainText) String 

func (pt *PlainText) String() string

func (*PlainText) UnmarshalIon added in v0.1.0 

func (pt *PlainText) UnmarshalIon(bin []byte) error

func (*PlainText) UnmarshalPEM added in v0.1.0 

func (pt *PlainText) UnmarshalPEM(data []byte) error

func (*PlainText) Verify added in v0.1.0 

func (pt *PlainText) Verify(pub ed25519.PublicKey) bool

type SelfConfig added in v1.6.1 

type SelfConfig struct {
	PeerConfig
	PrivateKey string `json:"priv"`
}

func (SelfConfig) Valid added in v1.6.1 

func (s SelfConfig) Valid() bool

type Signer added in v1.4.1 

type Signer interface {
	SigningKey() ed25519.PublicKey
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
goracle
goracle/subcommand
pemreader
pemreader reads PEM files from stdin and outputs plain text to stdout
 pemreader reads PEM files from stdin and outputs plain text to stdout

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.