jess

package module
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Nov 8, 2024 License: GPL-3.0 Imports: 21 Imported by: 14

README

Check out our main project at safing/portmaster

Jess

Jess is a cryptographic library and cli tool that focuses on usability and freedom.

Project Status:

  • Core Logic: production & audited
  • Go API: non-final production (breaking changes might happen)
  • CLI Tool: working alpha stage, rough around the edges

DISCLAIMER: Do not use in production yet! Use at your own risk.

Usage & Intro

Jess uses the theme of envelopes and letters in order to make everything a bit more comprehensible. Here is a list of terms that will prove helpful:

  • Signet ... private or secret key
  • Recipient ... public key
  • Envelope ... encryption configuration
  • Letter ... encrypted data with associated configuration
  • Trust Store ... a storage of everything you trust, your own keys and configurations, and your friends' public keys.

Jess makes heavy use of trust stores, which in its basic form is just a directory, where you can store your keys and configuration. You can either set a default one through an environment variable, or set it manually every time. This makes it easy to compartmentalize your trust zones.

Here is how you can setup a trust store and generate some keys:

export JESS_TSDIR=/tmp/truststore-test
jess generate --name Alice --scheme Ed25519
jess generate --name Alice --scheme ECDH-X25519
jess generate --name Bob --scheme Ed25519
jess generate --name Bob --scheme ECDH-X25519
jess generate --name BackupPassword --scheme pw
# look at result
jess manage

Now let's configure an envelope to get started with encrypting - set up an envelope to have Alice send Bob a file. Use the preset Encrypt for someone.

jess configure toBob
# look at result
jess manage

If now want to encrypt a file for Bob, you take a piece of data, put it in the envelope, and you have a letter!

echo "Hello, Bob!" > forbob.txt
jess close forbob.txt with toBob

And because we also have Bob's secret key, we can also go ahead and decrypt the file again.

jess open forbob.txt.letter -o -

Normally, of course, you would have a friend send you their recipient file (public key) and you would add it to your trust store.

In order to help you not screw up any configuration, Jess has the concept of requirements:

  • Confidentiality ... hide contents
  • Integrity ... check that nothing was modified
  • Recipient Authentication ... verify recipient
  • Sender Authentication ... verify sender

By default, all of them are required. If you, for some reason, do not require one ore more of them, you will have to disable them in the envelope for closing an envelope (encrypting) and pass the reduced requirements when opening a letter (decrypting).

In addition, if you are worried about weak algorithms, you can just pass a minimum security level (attack complexity as 2^n) that you require all algorithms to achieve. Jess does not contain any known weak algorithms, but if that changes, jess will warn you - after you upgraded to the new version.

Jess does not have a PKI or some sort of web of trust. You have to exchange public keys by yourself.

Jess is also capable of securing a network connection, but this currently only works with the library, not the CLI.

Building

Jess uses dep as the dependency manager.
After cloning the repo, run dep ensure.

The command line tool includes build information for debugging.
Please use the provided build script for building:

cd cmd
./build -o jess
./jess version
Architecture

Before we dive into technical details, here are some more/updated terms:

  • Tool/Scheme a cryptographic primitive/scheme
    • Identified via their Name/ID (used interchangeably)
  • Signet/Recipient a private/secret or public key
    • Identified by their ID (usually a UUID)
  • Envelope an encryption configuration, but also requirements
    • Identified by the name given to them

Every algorithm/piece that can be used to build a complete encryption operation is called a Tool. Tools have different capabilites and might cover more than just one primitive - eg. AES-GCM covers Confidentiality and Integrity.

Jess can either operate in single-op (eg. file encryption) or communication (eg. securing network traffic) mode.

Basically, every operation needs:

  • SenderAuthentication and ReceiverAuthentication:
    • PassDerivation: derive a key from given password
      • provides SenderAuthentication, ReceiverAuthentication
    • KeyExchange: supply trusted public key of peer comm mode only
      • provides ReceiverAuthentication
    • KeyEncapsulation: encrypt the key with trusted public key of peer
      • provides ReceiverAuthentication
    • Signing: sign the whole message
      • provides SenderAuthentication
  • KeyDerivation: guarantees clean key material, also more material than given may be needed.
  • Confidentiality:
    • Cipher: encrypt the data
    • IntegratedCipher: also provides Integrity
  • Integrity:
    • MAC: check data integrity
    • IntegratedCipher: also provides Confidentiality

Some of these properties may also be used multiple times. For example, you could choose to encrypt your data with multiple ciphers or use multiple MACs for data integrity checks.

Should any of these properties not be required, the user has to intentionally remove requirements.

In order to reduce the possibility of making unsuggested combinations of tools, the primary interface to choose tools is to use a suite:

The command jess list shows the available suites:

Name/ID   Provides   Security Level   Tools                                                                     Notes
key_v1    CIRS       128 b/s          HKDF(BLAKE2b-256), CHACHA20-POLY1305                                      recommended
pw_v1     CIRS       128 b/s          SCRYPT-20, HKDF(BLAKE2b-256), CHACHA20-POLY1305                           recommended
rcpt_v1   CIR        128 b/s          ECDH-X25519, HKDF(BLAKE2b-256), CHACHA20-POLY1305                         recommended
sign_v1   S          128 b/s          Ed25519(BLAKE2b-256)                                                      recommended
v1        CIRS       128 b/s          ECDH-X25519, Ed25519(BLAKE2b-256), HKDF(BLAKE2b-256), CHACHA20-POLY1305   recommended
w1        CIR        128 b/s          ECDH-X25519, HKDF(BLAKE2b-256), CHACHA20-POLY1305                         recommended
Specification

There is some more detail in SPEC.md.

Known Issues
Secure Key Deletion

Go currently does not provide functionality to securely handle sensitive data, such as key material, in memory. Thus, it cannot be guaranteed that key material is correctly wiped from memory and won't leak when swapping memory to disk.

There is an issue in the Golang project about this.

We evaluated two existing workarounds for this:

  1. Using reflect to dive into the internals of all algorithms to (possibly) delete key material. This is used in the Go implementation of Wireguard, for example. This still does not guarantee that Go internally deletes the key material.
  2. Use of the Go memguard package. While this would improve handling of key material that we directly manage, it will still not solve protecting all the intermediate values used in the implementations of the algorithms.

We currently settled on waiting for further progress on the issue by the Go development team, and will reevaluate the progress regularly.

Testing

Basically, tests are run like this:

go test

There is a special variable to enable very comprehensive testing:

go test -timeout 10m github.com/safing/jess -v -count=1 -cover -ldflags "-X github.com/safing/jess.RunComprehensiveTests=true"

There is some randomness to this, so you can use this command for predictable output in order to debug a problem:

go test -timeout 10m github.com/safing/jess -v -count=1 -cover -ldflags "-X github.com/safing/jess.RunComprehensiveTests=true -X github.com/safing/jess.RunTestsInDebugStyle=true"

# if you only want the comprehensive test itself:
go test -timeout 10m github.com/safing/jess -run ^TestCoreAllCombinations$ -v -count=1 -cover -ldflags "-X github.com/safing/jess.RunComprehensiveTests=true -X github.com/safing/jess.RunTestsInDebugStyle=true"

Documentation

Index

Constants

View Source 
const (
	ExportSenderKeyword = "sender"
	ExportSenderPrefix  = "sender:"

	ExportRecipientKeyword = "recipient"
	ExportRecipientPrefix  = "recipient:"

	ExportKeyKeyword = "secret"
	ExportKeyPrefix  = "secret:"

	ExportEnvelopeKeyword = "envelope"
	ExportEnvelopePrefix  = "envelope:"
)

Keywords and Prefixes for the export text format.

View Source 
const (
	Confidentiality uint8 = iota
	Integrity
	RecipientAuthentication
	SenderAuthentication
)

Security requirements of a letter.

View Source 
const (
	SignetSchemePassword = "pw"
	SignetSchemeKey      = "key"
)

Special signet types.

View Source 
const (
	SuiteStatusDeprecated  uint8 = 0
	SuiteStatusPermitted   uint8 = 1
	SuiteStatusRecommended uint8 = 2
)

Suite status options.

View Source 
const (
	FilterAny uint8 = iota
	FilterSignetOnly
	FilterRecipientOnly
)

TrustStore filter options.

Variables

View Source 
var (
	RecommendedNetwork         = []string{"ECDH-X25519", "HKDF(SHA2-256)", "CHACHA20-POLY1305"}
	RecommendedStoragePassword = []string{"PBKDF2-SHA2-256", "HKDF(SHA2-256)", "CHACHA20-POLY1305"}
	RecommendedStorageKey      = []string{"HKDF(SHA2-256)", "CHACHA20-POLY1305"}

	RecommendedStorageRecipient = []string{"ECDH-X25519", "HKDF(SHA2-256)", "CHACHA20-POLY1305"}

	RecommendedSigning = []string{"Ed25519(SHA2-256)"}
)

Currently recommended toolsets.

View Source 
var (
	// ErrIntegrityViolation is returned when the integrity was found the be violated.
	ErrIntegrityViolation = errors.New("integrity violation")
	// ErrConfidentialityViolation is returned when the confidentiality was found the be violated.
	ErrConfidentialityViolation = errors.New("confidentiality violation")
	// ErrAuthenticityViolation is returned when the authenticity was found the be violated.
	ErrAuthenticityViolation = errors.New("authenticity violation")

	// ErrInsufficientRandom is returned if the configured RNG cannot deliver enough data.
	ErrInsufficientRandom = errors.New("not enough random data available from source")
)
View Source 
var (
	// SuiteKey is a cipher suite for encryption with a key.
	SuiteKey = SuiteKeyV1
	// SuitePassword is a cipher suite for encryption with a password.
	SuitePassword = SuitePasswordV1
	// SuiteRcptOnly is a cipher suite for encrypting for someone, but without verifying the sender/source.
	SuiteRcptOnly = SuiteRcptOnlyV1
	// SuiteSign is a cipher suite for signing (no encryption).
	SuiteSign = SuiteSignV1
	// SuiteSignFile is a cipher suite for signing files (no encryption).
	SuiteSignFile = SuiteSignFileV1
	// SuiteComplete is a cipher suite for both encrypting for someone and signing.
	SuiteComplete = SuiteCompleteV1
	// SuiteWire is a cipher suite for network communication, including authentication of the server, but not the client.
	SuiteWire = SuiteWireV1
)

Currently Recommended Suites.

View Source 
var (
	// SuiteKeyV1 is a cipher suite for encryption with a key.
	SuiteKeyV1 = registerSuite(&Suite{
		ID:            "key_v1",
		Tools:         []string{"HKDF(BLAKE2b-256)", "CHACHA20-POLY1305"},
		Provides:      NewRequirements(),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
	// SuitePasswordV1 is a cipher suite for encryption with a password.
	SuitePasswordV1 = registerSuite(&Suite{
		ID:            "pw_v1",
		Tools:         []string{"SCRYPT-20", "HKDF(BLAKE2b-256)", "CHACHA20-POLY1305"},
		Provides:      NewRequirements(),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
	// SuiteRcptOnlyV1 is a cipher suite for encrypting for someone, but without verifying the sender/source.
	SuiteRcptOnlyV1 = registerSuite(&Suite{
		ID:            "rcpt_v1",
		Tools:         []string{"ECDH-X25519", "HKDF(BLAKE2b-256)", "CHACHA20-POLY1305"},
		Provides:      NewRequirements().Remove(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
	// SuiteSignV1 is a cipher suite for signing (no encryption).
	SuiteSignV1 = registerSuite(&Suite{
		ID:            "sign_v1",
		Tools:         []string{"Ed25519(BLAKE2b-256)"},
		Provides:      newEmptyRequirements().Add(Integrity).Add(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
	// SuiteSignFileV1 is a cipher suite for signing files (no encryption).
	// SHA2_256 is chosen for better compatibility with other tool sets and workflows.
	SuiteSignFileV1 = registerSuite(&Suite{
		ID:            "signfile_v1",
		Tools:         []string{"Ed25519(SHA2-256)"},
		Provides:      newEmptyRequirements().Add(Integrity).Add(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
	// SuiteCompleteV1 is a cipher suite for both encrypting for someone and signing.
	SuiteCompleteV1 = registerSuite(&Suite{
		ID:            "v1",
		Tools:         []string{"ECDH-X25519", "Ed25519(BLAKE2b-256)", "HKDF(BLAKE2b-256)", "CHACHA20-POLY1305"},
		Provides:      NewRequirements(),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
	// SuiteWireV1 is a cipher suite for network communication, including authentication of the server, but not the client.
	SuiteWireV1 = registerSuite(&Suite{
		ID:            "w1",
		Tools:         []string{"ECDH-X25519", "HKDF(BLAKE2b-256)", "CHACHA20-POLY1305"},
		Provides:      NewRequirements().Remove(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusRecommended,
	})
)
View Source 
var (
	// SuiteKeyV2 is a cipher suite for encryption with a key.
	SuiteKeyV2 = registerSuite(&Suite{
		ID:            "key_v2",
		Tools:         []string{"BLAKE3-KDF", "CHACHA20-POLY1305"},
		Provides:      NewRequirements(),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
	// SuitePasswordV2 is a cipher suite for encryption with a password.
	SuitePasswordV2 = registerSuite(&Suite{
		ID:            "pw_v2",
		Tools:         []string{"SCRYPT-20", "BLAKE3-KDF", "CHACHA20-POLY1305"},
		Provides:      NewRequirements(),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
	// SuiteRcptOnlyV2 is a cipher suite for encrypting for someone, but without verifying the sender/source.
	SuiteRcptOnlyV2 = registerSuite(&Suite{
		ID:            "rcpt_v2",
		Tools:         []string{"ECDH-X25519", "BLAKE3-KDF", "CHACHA20-POLY1305"},
		Provides:      NewRequirements().Remove(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
	// SuiteSignV2 is a cipher suite for signing (no encryption).
	SuiteSignV2 = registerSuite(&Suite{
		ID:            "sign_v2",
		Tools:         []string{"Ed25519(BLAKE3)"},
		Provides:      newEmptyRequirements().Add(Integrity).Add(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
	// SuiteSignFileV2 is a cipher suite for signing files (no encryption).
	// SHA2_256 is chosen for better compatibility with other tool sets and workflows.
	SuiteSignFileV2 = registerSuite(&Suite{
		ID:            "signfile_v2",
		Tools:         []string{"Ed25519(BLAKE3)"},
		Provides:      newEmptyRequirements().Add(Integrity).Add(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
	// SuiteCompleteV2 is a cipher suite for both encrypting for someone and signing.
	SuiteCompleteV2 = registerSuite(&Suite{
		ID:            "v2",
		Tools:         []string{"ECDH-X25519", "Ed25519(BLAKE3)", "BLAKE3-KDF", "CHACHA20-POLY1305"},
		Provides:      NewRequirements(),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
	// SuiteWireV2 is a cipher suite for network communication, including authentication of the server, but not the client.
	SuiteWireV2 = registerSuite(&Suite{
		ID:            "w2",
		Tools:         []string{"ECDH-X25519", "BLAKE3-KDF", "CHACHA20-POLY1305"},
		Provides:      NewRequirements().Remove(SenderAuthentication),
		SecurityLevel: 128,
		Status:        SuiteStatusPermitted,
	})
)
View Source 
var (
	ErrSignetNotFound   = errors.New("could not find signet")
	ErrEnvelopeNotFound = errors.New("could not find envelope")
)

TrustStore errors.

View Source 
var ErrIncompatibleFileFormatVersion = errors.New("incompatible file format version")

ErrIncompatibleFileFormatVersion is returned when an incompatible wire format is encountered.

View Source 
var ErrIncompatibleWireFormatVersion = errors.New("incompatible wire format version")

ErrIncompatibleWireFormatVersion is returned when an incompatible wire format is encountered.

Functions

func Burn 

func Burn(data ...[]byte)

Burn gets rid of the given []byte slice(s). This is currently ineffective, see known issues in the project's README.

func CalculatePasswordSecurityLevel 

func CalculatePasswordSecurityLevel(password string, iterations int) int

CalculatePasswordSecurityLevel calculates the security level of the given password and iterations of the pbkdf algorithm.

func Random 

func Random() io.Reader

Random returns the io.Reader for reading randomness. By default, it uses crypto/rand.Reader.

func RandomBytes 

func RandomBytes(n int) ([]byte, error)

RandomBytes returns the specified amount of random bytes in a []byte slice. By default, it uses crypto/rand.Reader.

func SetCustomRNG 

func SetCustomRNG(randReader io.Reader)

SetCustomRNG sets a custom RNG to be used with jess.

func SetDefaultKeySize 

func SetDefaultKeySize(sizeInBytes int)

SetDefaultKeySize sets a global default key size to be used as a fallback value. This will be only used if the default key size could not be derived from already present information.

func SetMinimumSecurityLevel 

func SetMinimumSecurityLevel(securityLevel int)

SetMinimumSecurityLevel sets a global minimum security level. Jess will refuse any operations that violate this security level.

func SetPasswordCallbacks 

func SetPasswordCallbacks(
	createPassword func(signet *Signet, minSecurityLevel int) error,
	getPassword func(signet *Signet) error,
)

SetPasswordCallbacks sets callbacks that are used to let the user enter passwords.

func SuitesMap 

func SuitesMap() map[string]*Suite

SuitesMap returns all registered suites as a map.

Types

type Envelope 

type Envelope struct {
	Version uint8
	Name    string
	SuiteID string

	// Secret keys and passwords
	Secrets []*Signet

	// Sender related signets
	// When closing: private keys for signatures
	// When opening: public keys for signatures
	Senders []*Signet

	// Recipient related signets
	// When closing: public keys for key exchange or key encapsulation
	// When opening: private keys for key exchange or key encapsulation
	Recipients []*Signet

	// SecurityLevel is the security level of the envelope when it was created
	SecurityLevel int
	// contains filtered or unexported fields
}

Envelope holds configuration for jess to put data into a letter.

func EnvelopeFromBase58 added in v0.3.0 

func EnvelopeFromBase58(base58Encoded string) (*Envelope, error)

EnvelopeFromBase58 parses and loads a base58 encoded serialized envelope.

func EnvelopeFromBytes added in v0.3.0 

func EnvelopeFromBytes(data []byte) (*Envelope, error)

EnvelopeFromBytes parses and loads a serialized envelope.

func EnvelopeFromTextFormat added in v0.3.0 

func EnvelopeFromTextFormat(textFormat string) (*Envelope, error)

EnvelopeFromTextFormat loads an envelope from the text format.

func NewUnconfiguredEnvelope 

func NewUnconfiguredEnvelope() *Envelope

NewUnconfiguredEnvelope returns an unconfigured, but slightly initialized envelope.

func (*Envelope) Check 

func (e *Envelope) Check(trustStore TrustStore) error

Check returns whether the envelope is valid and can be used as is.

func (*Envelope) CleanSignets added in v0.3.0 

func (e *Envelope) CleanSignets()

CleanSignets cleans all the signets from all the non-necessary data as well as key material. This is for preparing for serializing and saving the signet.

func (*Envelope) Correspondence 

func (e *Envelope) Correspondence(trustStore TrustStore) (*Session, error)

Correspondence returns a new session configured with the envelope.

func (*Envelope) Export added in v0.3.0 

func (e *Envelope) Export(short bool) (textFormat string, err error)

Export exports the envelope in text format.

func (*Envelope) LoadSuite 

func (e *Envelope) LoadSuite() error

LoadSuite loads the suite specified in the envelope.

func (*Envelope) LoopRecipients 

func (e *Envelope) LoopRecipients(scheme string, fn func(*Signet) error) error

LoopRecipients loops over all recipient signets of the given scheme.

func (*Envelope) LoopSecrets 

func (e *Envelope) LoopSecrets(scheme string, fn func(*Signet) error) error

LoopSecrets loops over all secrets of the given scheme.

func (*Envelope) LoopSenders 

func (e *Envelope) LoopSenders(scheme string, fn func(*Signet) error) error

LoopSenders loops over all sender signets of the given scheme.

func (*Envelope) PrepareSignets 

func (e *Envelope) PrepareSignets(storage TrustStore) error

PrepareSignets checks that all signets of the envelope are ready to use. It will fetch referenced signets and load the keys.

func (*Envelope) ReloadSuite 

func (e *Envelope) ReloadSuite() error

ReloadSuite forces reloading the suite specified in the envelope.

func (*Envelope) Suite 

func (e *Envelope) Suite() *Suite

Suite returns the loaded suite.

func (*Envelope) ToBase58 added in v0.3.0 

func (e *Envelope) ToBase58() (string, error)

ToBase58 serializes the envelope and encodes it with base58.

func (*Envelope) ToBytes added in v0.3.0 

func (e *Envelope) ToBytes() ([]byte, error)

ToBytes serializes the envelope to a byte slice.

func (*Envelope) WireCorrespondence 

func (e *Envelope) WireCorrespondence(trustStore TrustStore) (*Session, error)

WireCorrespondence returns a new wire session (live communication) configured with the envelope.

type Helper 

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

Helper provides a basic interface for tools to access session properties and functionality.

func (*Helper) Burn 

func (h *Helper) Burn(data ...[]byte)

Burn gets rid of the given []byte slice(s). This is currently ineffective, see known issues in the project's README.

func (*Helper) DefaultSymmetricKeySize 

func (h *Helper) DefaultSymmetricKeySize() int

DefaultSymmetricKeySize returns the default key size for this session.

func (*Helper) FillNewSessionKey 

func (h *Helper) FillNewSessionKey(key []byte) error

FillNewSessionKey fills the given []byte slice with a new session key (or nonce).

func (*Helper) MaxSecurityLevel 

func (h *Helper) MaxSecurityLevel() int

MaxSecurityLevel returns the (highest) security level for this session.

func (*Helper) NewSessionKey 

func (h *Helper) NewSessionKey() ([]byte, error)

NewSessionKey returns a new session key in tool's specified length.

func (*Helper) NewSessionNonce 

func (h *Helper) NewSessionNonce() ([]byte, error)

NewSessionNonce returns a new session nonce in tool's specified length.

func (*Helper) Random 

func (h *Helper) Random() io.Reader

Random returns the io.Reader for reading randomness.

func (*Helper) RandomBytes 

func (h *Helper) RandomBytes(n int) ([]byte, error)

RandomBytes returns the specified amount of random bytes in a []byte slice.

func (*Helper) SecurityLevel 

func (h *Helper) SecurityLevel() int

SecurityLevel returns the effective (ie. lowest) security level for this session.

type Letter 

type Letter struct {
	Version uint8  // signed, MAC'd (may not exist when wired)
	SuiteID string // signed, MAC'd (may not exist when wired)

	Nonce []byte  // signed, MAC'd
	Keys  []*Seal `json:",omitempty"` // signed, MAC'd

	Data       []byte  `json:",omitempty"` // signed, MAC'd
	Mac        []byte  `json:",omitempty"` // signed
	Signatures []*Seal `json:",omitempty"`

	// Flags for wire protocol
	ApplyKeys bool `json:",omitempty"` // MAC'd
}

Letter is the data format for encrypted data at rest or in transit.

func LetterFromDSD 

func LetterFromDSD(data []byte) (*Letter, error)

LetterFromDSD loads a dsd-serialized letter.

func LetterFromFileFormat 

func LetterFromFileFormat(c *container.Container) (*Letter, error)

LetterFromFileFormat parses a letter stored as a file.

func LetterFromJSON 

func LetterFromJSON(data []byte) (*Letter, error)

LetterFromJSON loads a json-serialized letter.

func LetterFromWire 

func LetterFromWire(c *container.Container) (*Letter, error)

LetterFromWire parses a letter sent over a network connection.

func LetterFromWireData deprecated 

func LetterFromWireData(data []byte) (*Letter, error)

LetterFromWireData is a relay to LetterFromWire to quickly fix import issues of godep.

Deprecated: Please use LetterFromWire with a fresh container directly.

func (*Letter) Envelope 

func (letter *Letter) Envelope(requirements *Requirements) (*Envelope, error)

Envelope returns an envelope built from the letter, configured for opening it.

func (*Letter) Open 

func (letter *Letter) Open(requirements *Requirements, trustStore TrustStore) ([]byte, error)

Open creates a session and opens the letter in one step.

func (*Letter) ToDSD 

func (letter *Letter) ToDSD(dsdFormat uint8) ([]byte, error)

ToDSD serializes the letter to the given dsd format.

func (*Letter) ToFileFormat 

func (letter *Letter) ToFileFormat() (*container.Container, error)

ToFileFormat serializes the letter for storing it as a file.

func (*Letter) ToJSON 

func (letter *Letter) ToJSON() ([]byte, error)

ToJSON serializes the letter to json.

func (*Letter) ToWire 

func (letter *Letter) ToWire() (*container.Container, error)

ToWire serializes to letter for sending it over a network connection.

func (*Letter) Verify 

func (letter *Letter) Verify(requirements *Requirements, trustStore TrustStore) error

Verify creates a session and verifies the letter in one step.

func (*Letter) WireCorrespondence 

func (letter *Letter) WireCorrespondence(trustStore TrustStore) (*Session, error)

WireCorrespondence creates a wire session (communication over a network connection) from a letter.

type MemTrustStore 

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

MemTrustStore is a simple trust store using a Go map as backend.

func NewMemTrustStore 

func NewMemTrustStore() *MemTrustStore

NewMemTrustStore returns a new in-memory TrustStore.

func (*MemTrustStore) DeleteSignet 

func (mts *MemTrustStore) DeleteSignet(id string, recipient bool) error

DeleteSignet deletes the Signet or Recipient with the given ID.

func (*MemTrustStore) GetSignet 

func (mts *MemTrustStore) GetSignet(id string, recipient bool) (*Signet, error)

GetSignet returns the Signet with the given ID.

func (*MemTrustStore) SelectSignets 

func (mts *MemTrustStore) SelectSignets(filter uint8, schemes ...string) ([]*Signet, error)

SelectSignets returns a selection of the signets in the trust store. Results are filtered by tool/algorithm and whether it you're looking for a signet (private key) or a recipient (public key).

func (*MemTrustStore) StoreSignet 

func (mts *MemTrustStore) StoreSignet(signet *Signet) error

StoreSignet stores a Signet in the TrustStore.

type Requirements 

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

Requirements describe security properties.

func NewRequirements 

func NewRequirements() *Requirements

NewRequirements returns an attribute instance with all requirements.

func ParseRequirementsFromNoSpec 

func ParseRequirementsFromNoSpec(no string) (*Requirements, error)

ParseRequirementsFromNoSpec parses the requirements from a negated "No" string.

func (*Requirements) Add 

func (requirements *Requirements) Add(attribute uint8) *Requirements

Add adds an attribute.

func (*Requirements) CheckComplianceTo 

func (requirements *Requirements) CheckComplianceTo(requirement *Requirements) error

CheckComplianceTo checks if the requirements are compliant to the given required requirements.

func (*Requirements) Empty 

func (requirements *Requirements) Empty() bool

Empty returns whether the requirements are empty.

func (*Requirements) Has 

func (requirements *Requirements) Has(attribute uint8) bool

Has returns whether the requirements contain the given attribute.

func (*Requirements) Remove 

func (requirements *Requirements) Remove(attribute uint8) *Requirements

Remove removes an attribute.

func (*Requirements) SerializeToNoSpec 

func (requirements *Requirements) SerializeToNoSpec() string

SerializeToNoSpec returns the requirements as a negated "No" string.

func (*Requirements) ShortString 

func (requirements *Requirements) ShortString() string

ShortString returns a short string representation of the requirements.

func (*Requirements) String 

func (requirements *Requirements) String() string

String returns a string representation of the requirements.

type Seal 

type Seal struct {
	Scheme string `json:",omitempty"`

	// Key Establishment: Signet ID of recipient's signet
	// Signature: Signet ID of signer's signet
	ID string `json:",omitempty"`

	// Key Establishment: Public key or wrapped key
	// Signature: Signature value
	Value []byte `json:",omitempty"`
}

Seal holds a key, key exchange or signature within a letter.

type Session 

type Session struct {
	DefaultSymmetricKeySize int
	SecurityLevel           int
	// contains filtered or unexported fields
}

Session holds session information for operations using the envelope it was initialized with.

func (*Session) Close 

func (s *Session) Close(data []byte) (*Letter, error)

Close encrypts (and possibly signs) the given data and returns a Letter. Storyline: Close takes an envelope, inserts the message and closes it, resulting in a letter.

func (*Session) NonceSize 

func (s *Session) NonceSize() int

NonceSize returns the nonce size to use for new letters.

func (*Session) Open 

func (s *Session) Open(letter *Letter) ([]byte, error)

Open decrypts (and possibly verifies) the given letter and returns the original data. Storyline: Open takes a letter, checks any seals, opens it and returns the message.

func (*Session) Server 

func (s *Session) Server()

Server marks a wire session as being in the role of the server, rather than the client.

func (*Session) Verify 

func (s *Session) Verify(letter *Letter) error

Verify verifies signatures of the given letter.

type Signet 

type Signet struct {
	Version uint8
	ID      string
	Scheme  string

	Key        []byte
	Public     bool      `json:",omitempty"` // key is the public part of a key pair
	Protection *Envelope `json:",omitempty"` // key is a serialized letter

	// Metadata about Signet
	Info *SignetInfo `json:",omitempty"`

	// Signature of Version, Scheme, Key, Public, Protected, Info
	Signature *Letter `json:",omitempty"`
	// contains filtered or unexported fields
}

Signet describes a cryptographic key pair. Passwords and Keys may also be wrapped in a Signet for easier integration.

func GenerateSignet 

func GenerateSignet(toolID string, securityLevel int) (*Signet, error)

GenerateSignet returns a new signet with a freshly generated key.

func KeyFromTextFormat added in v0.3.0 

func KeyFromTextFormat(textFormat string) (*Signet, error)

KeyFromTextFormat loads a secret key from the text format.

func NewSignetBase 

func NewSignetBase(tool *tools.Tool) *Signet

NewSignetBase creates a new signet base without a key.

func RecipientFromTextFormat added in v0.3.0 

func RecipientFromTextFormat(textFormat string) (*Signet, error)

RecipientFromTextFormat loads a recipient (public key) from the text format.

func SenderFromTextFormat added in v0.3.0 

func SenderFromTextFormat(textFormat string) (*Signet, error)

SenderFromTextFormat loads a sender (private key) from the text format.

func SignetFromBase58 added in v0.3.0 

func SignetFromBase58(base58Encoded string) (*Signet, error)

SignetFromBase58 parses and loads a base58 encoded serialized signet.

func SignetFromBytes added in v0.3.0 

func SignetFromBytes(data []byte) (*Signet, error)

SignetFromBytes parses and loads a serialized signet.

func (*Signet) AsRecipient 

func (signet *Signet) AsRecipient() (*Signet, error)

AsRecipient returns a public version of the Signet.

func (*Signet) AssignUUID 

func (signet *Signet) AssignUUID() error

AssignUUID generates a (new) UUID for the Signet.

func (*Signet) Backup added in v0.3.0 

func (signet *Signet) Backup(short bool) (textFormat string, err error)

Backup exports the private part of a signet in text format.

func (*Signet) Burn 

func (signet *Signet) Burn() error

Burn destroys all the key material and renders the Signet unusable. This is currently ineffective, see known issues in the project's README.

func (*Signet) Export added in v0.3.0 

func (signet *Signet) Export(short bool) (textFormat string, err error)

Export exports the public part of a signet in text format.

func (*Signet) GenerateKey 

func (signet *Signet) GenerateKey() error

GenerateKey generates a new key. Will not operate if key is already present.

func (*Signet) GetStoredKey 

func (signet *Signet) GetStoredKey() (key []byte, public bool)

GetStoredKey returns the stored key and whether it is public.

func (*Signet) LoadKey 

func (signet *Signet) LoadKey() error

LoadKey loads the serialized key pair.

func (*Signet) PrivateKey 

func (signet *Signet) PrivateKey() crypto.PrivateKey

PrivateKey returns the private key or nil, if there is none.

func (*Signet) PublicKey 

func (signet *Signet) PublicKey() crypto.PublicKey

PublicKey returns the public key.

func (*Signet) SetLoadedKeys 

func (signet *Signet) SetLoadedKeys(pubKey crypto.PublicKey, privKey crypto.PrivateKey)

SetLoadedKeys sets the loaded public and private keys.

func (*Signet) SetStoredKey 

func (signet *Signet) SetStoredKey(key []byte, public bool)

SetStoredKey sets a new stored key and whether it is public.

func (*Signet) StoreKey 

func (signet *Signet) StoreKey() error

StoreKey serializes the loaded key pair.

func (*Signet) ToBase58 added in v0.3.0 

func (signet *Signet) ToBase58() (string, error)

ToBase58 serializes the signet and encodes it with base58.

func (*Signet) ToBytes added in v0.3.0 

func (signet *Signet) ToBytes() ([]byte, error)

ToBytes serializes the Signet to a byte slice.

func (*Signet) Tool 

func (signet *Signet) Tool() (*tools.Tool, error)

Tool returns the tool of the signet.

func (*Signet) Verify 

func (signet *Signet) Verify() error

Verify verifies the signature of the signet.

type SignetInfo 

type SignetInfo struct {
	Name    string
	Owner   string
	Created time.Time
	Expires time.Time

	Details [][2]string
}

SignetInfo holds human readable meta information about a signet.

type Suite 

type Suite struct {
	ID            string
	Tools         []string
	Provides      *Requirements
	SecurityLevel int
	Status        uint8
}

Suite describes a cipher suite - a set of algorithms and the attributes they provide.

func GetSuite 

func GetSuite(suiteID string) (suite *Suite, ok bool)

GetSuite returns the suite with the given ID.

func Suites 

func Suites() []*Suite

Suites returns all registered suites as a slice.

type TrustStore 

type TrustStore interface {
	// GetSignet returns the Signet with the given ID.
	GetSignet(id string, recipient bool) (*Signet, error)
}

TrustStore holds a set of trusted Signets and Recipients.

type WireSession 

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

WireSession holds session information specific to communication over a network connection.

Source Files

View all Source files

Directories

Path Synopsis
Package lhash provides integrated labeled hashes.
 Package lhash provides integrated labeled hashes.
Package supply provides a cache of signets for pre-generating signets.
 Package supply provides a cache of signets for pre-generating signets.
all
Package all imports all tool subpackages
 Package all imports all tool subpackages
blake3
ecdh
gostdlib

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.