tools

package
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: 7 Imported by: 2

Documentation

Index

Constants

View Source 
const (

	// PurposeKeyDerivation declares key derivation capabilities.
	PurposeKeyDerivation uint8 = iota + 1

	// PurposePassDerivation declares password derivation capabilties (make a secure key out of a password).
	// Provides SenderAuthentication, ReceiverAuthentication requirements.
	PurposePassDerivation

	// PurposeKeyExchange declares (DH-style) key exchange capabilities.
	// A trusted key of the receiver must be supplied.
	// Provides ReceiverAuthentication attribute.
	PurposeKeyExchange

	// PurposeKeyEncapsulation declares key encapsulation capabilities (key is encrypted with the receivers public key)
	// A trusted key of the receiver must be supplied.
	// Provides ReceiverAuthentication attribute.
	PurposeKeyEncapsulation

	// PurposeSigning declares signing capabilities.
	// The receiver must already have the public key.
	// Provides SenderAuthentication attribute. Theoretically also provides integrity, but as signing is done after everything else, it will not be able to detect a wrong key during decryption.
	PurposeSigning

	// PurposeIntegratedCipher declares that the tool provides both encryption and integrity verification capabilities.
	// Provies Confidentiality and Integrity requirements.
	PurposeIntegratedCipher

	// PurposeCipher declares that the tool provides encryption capabilities.
	// Provies Confidentiality attribute.
	PurposeCipher

	// PurposeMAC declares that the tool provides integrity verification capabilities.
	// Provies Integrity attribute.
	PurposeMAC
)

Tool Purposes.

View Source 
const (

	// OptionStreaming declares that the tool can work with streaming data and might be given a io.Reader and io.Writer instead of just a []byte slice.
	// TODO: Implementation pending.
	OptionStreaming uint8 = iota + 1

	// OptionNeedsManagedHasher declares that the tool requires a hashing algorithm to work. It will automatically hash everything that needs to be authenticated and may be shared with other algorithms.
	OptionNeedsManagedHasher

	// OptionNeedsDedicatedHasher declares that the tool requires a hashing algorithm to work. It will get its own instance and will have to do all the work itself.
	OptionNeedsDedicatedHasher

	// OptionNeedsSecurityLevel declares that the tool requires a specified security level. This will be derived from the rest of the used tools, or must be specified by the user directly.
	OptionNeedsSecurityLevel

	// OptionNeedsDefaultKeySize declares that the tool requires a default key size for operation. This will be derived from the rest of the used tools, or must be specified by the user directly.
	OptionNeedsDefaultKeySize

	// OptionHasState declares that the tool has an internal state and requires the setup and reset routines to be run before/after usage. KeyDerivation tools do not have to declare this, their state is handled separately.
	OptionHasState
)

Tool Options.

Variables

View Source 
var (
	// ErrNotFound is returned when a tool cannot be found.
	ErrNotFound = errors.New("does not exist")

	// ErrInvalidKey is returned when a invalid public or private key was supplied.
	ErrInvalidKey = errors.New("invalid key")

	// ErrNotImplemented is returned by the dummy functions if they are not overridden correctly.
	ErrNotImplemented = errors.New("not implemented")

	// ErrProtected is returned if an operation is executed, but the key is still protected.
	ErrProtected = errors.New("key is protected")
)

Functions

func AsMap 

func AsMap() map[string]*Tool

AsMap returns all Tools in a map. The returned map must not be modified.

func Register 

func Register(tool *Tool)

Register registers a new Tool. This function may only be called in init() functions.

Types

type HelperInt 

type HelperInt interface {
	// NewSessionKey returns a new session key (or nonce) in tool's specified length.
	NewSessionKey() ([]byte, error)

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

	// NewSessionNonce returns a new session nonce in tool's specified length.
	NewSessionNonce() ([]byte, error)

	// Random returns the io.Reader for reading randomness.
	Random() io.Reader

	// RandomBytes returns the specified amount of random bytes in a []byte slice.
	RandomBytes(n int) ([]byte, error)

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

	// DefaultSymmetricKeySize returns the default key size for this session.
	DefaultSymmetricKeySize() int

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

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

HelperInt is an interface to Helper.

type SignetInt 

type SignetInt interface {
	// GetStoredKey returns the stored key and whether it is public.
	GetStoredKey() (key []byte, public bool)

	// SetStoredKey sets a new stored key and whether it is public.
	SetStoredKey(newKey []byte, public bool)

	// PublicKey returns the public key.
	PublicKey() crypto.PublicKey

	// PrivateKey returns the private key or nil, if there is none.
	PrivateKey() crypto.PrivateKey

	// SetLoadedKeys sets the loaded public and private keys.
	SetLoadedKeys(pubKey crypto.PublicKey, privKey crypto.PrivateKey)

	// LoadKey loads the serialized key pair.
	LoadKey() error
}

SignetInt is a minimal interface to Signet.

type Tool 

type Tool struct {
	// Info is a globally shared instance of generic tool information.
	Info *ToolInfo

	// StaticLogic holds a static (and possibly even nil) value of the tool logic in order to access certain handling methods.
	StaticLogic ToolLogic

	// Factory returns an initialized (but not yet set up) instance of ToolLogic.
	// Setup is done after initialization by overriding Setup().
	Factory func() ToolLogic
}

Tool describes a cryptographic tool and is split into information and logic parts.

func AsList 

func AsList() []*Tool

AsList returns all Tools in a slice. The returned slice must not be modified.

func Get 

func Get(name string) (*Tool, error)

Get returns the Tool with the given name.

type ToolInfo 

type ToolInfo struct {
	Name string

	Purpose uint8
	Options []uint8

	KeySize       int // in bytes
	NonceSize     int // in bytes
	SecurityLevel int // approx. attack complexity as 2^n

	Comment string
	Author  string
}

ToolInfo holds generic information about a tool.

func (*ToolInfo) FormatOptions 

func (ti *ToolInfo) FormatOptions() string

FormatOptions returns a list of names of the declared options.

func (*ToolInfo) FormatPurpose 

func (ti *ToolInfo) FormatPurpose() string

FormatPurpose returns the name of the declared purpose.

func (*ToolInfo) HasOption 

func (ti *ToolInfo) HasOption(option uint8) bool

HasOption returns whether the *ToolInfo has the given option.

func (*ToolInfo) With 

func (ti *ToolInfo) With(changes *ToolInfo) *ToolInfo

With uses the original ToolInfo as a template for a new ToolInfo and returns the new ToolInfo.

type ToolLogic 

type ToolLogic interface {

	// Init is called by the internal tool initialized procedure and is called by New().  Do not override.
	Init(tool *Tool, helper HelperInt, hashTool *hashtools.HashTool, hashSumFn func() ([]byte, error))

	// Info returns information about the Tool. Init is only called once per ToolLogic instance. Do not override.
	Info() *ToolInfo
	// Definition returns Tool's definition. Do not override.
	Definition() *Tool
	// Factory returns a new instance of the ToolLogic. Do not override.
	Factory() ToolLogic
	// Helper returns a Helper. Do not override.
	Helper() HelperInt
	// HashTool returns the assigned HashTool. Do not override.
	HashTool() *hashtools.HashTool
	// ManagedHashSum returns the hashsum of the managed hasher. Must be enabled by the tool by declaring FeatureNeedsManagedHasher. Do not override.
	ManagedHashSum() ([]byte, error)

	// Setup is called after Init and can be used the tool to do some custom setup before being used. It is called before every use of the ToolLogic instance. Override at will.
	// If a Tool needs key material, it needs to be requested here.
	Setup() error

	// Reset is called after all operations have finished and should be used to do some cleanup, burn all key material and prepare for the next usage. It is called after every use of the ToolLogic instance. Override at will.
	Reset() error

	// DeriveKeyFromPassword takes a password and turns it into a key.
	// Must be overridden by tools that declare FeaturePassDerivation.
	DeriveKeyFromPassword(password []byte, salt []byte) ([]byte, error)

	// InitKeyDerivation initializes the key generation.
	// Must be overridden by tools that declare FeatureKeyDerivation.
	InitKeyDerivation(nonce []byte, material ...[]byte) error

	// DeriveKey derives a new key.
	// Must be overridden by tools that declare FeatureKeyDerivation.
	DeriveKey(size int) ([]byte, error)

	// DeriveKeyWriteTo derives a new key and writes it into the given slice.
	// Must be overridden by tools that declare FeatureKeyDerivation.
	DeriveKeyWriteTo(newKey []byte) error

	// MakeSharedKey takes a local private key and a remote public key and generates a shared secret.
	// Must be overridden by tools that declare FeatureKeyExchange.
	MakeSharedKey(local SignetInt, remote SignetInt) ([]byte, error)

	// EncapsulateKey wraps a key using the given Signet (remote public key).
	// Must be overridden by tools that declare FeatureKeyEncapsulation.
	EncapsulateKey(key []byte, remote SignetInt) ([]byte, error)

	// EncapsulateKey unwraps an encapsulated key using the given Signet (local private key).
	// Must be overridden by tools that declare FeatureKeyEncapsulation.
	UnwrapKey(wrappedKey []byte, local SignetInt) ([]byte, error)

	// Encrypt encrypts the given data.
	// Must be overridden by tools that declare FeatureCipher.
	Encrypt(data []byte) ([]byte, error)

	// Decrypt decrypts the given data.
	// Must be overridden by tools that declare FeatureCipher.
	Decrypt(data []byte) ([]byte, error)

	// Encrypt encrypts the given data, and authenticates both data and associatedData.
	// Must be overridden by tools that declare FeatureIntegratedCipher.
	AuthenticatedEncrypt(data, associatedData []byte) ([]byte, error)

	// Decrypt decrypts the given data, and authenticates both data and associatedData.
	// Must be overridden by tools that declare FeatureIntegratedCipher.
	AuthenticatedDecrypt(data, associatedData []byte) ([]byte, error)

	// MAC returns a message authentication code for the given data and associatedData. If the Tool uses a managed hasher, it will be ready for fetching the sum of both. In that case, no data has to be processed again.
	// Must be overridden by tools that declare FeatureMAC.
	MAC(data, associatedData []byte) ([]byte, error)

	// Sign signs the data with the given Signet (local private key).
	// Must be overridden by tools that declare FeatureSigning.
	Sign(data, associatedData []byte, local SignetInt) ([]byte, error)

	// Verify verifies the signature of the data using the given signature and Signet (remote public key).
	// Must be overridden by tools that declare FeatureSigning.
	Verify(data, associatedData, signature []byte, remote SignetInt) error

	// LoadKey loads a key from the Signet's key storage (`Key`) into the Signet's cache (`Loaded*`). If the Signet is marked as public, the storage is expected to only have the public key present, only it will be loaded.
	// Must work with a static (no Setup()) ToolLogic.
	// Must be overridden by tools that declare FeatureKeyExchange, FeatureKeyEncapsulation or FeatureSigning.
	LoadKey(SignetInt) error

	// StoreKey stores a loaded key from the Signet's cache (`Loaded*`) in the Signet's key storage (`Key`). If the Signet is marked as public, only the public key will be stored.
	// Must work with a static (no Setup()) ToolLogic.
	// Must be overridden by tools that declare FeatureKeyExchange, FeatureKeyEncapsulation or FeatureSigning.
	StoreKey(SignetInt) error

	// GenerateKey generates a new key pair and stores it in the given Signet. They key pair is not stored in the Signet's key storage (`Key`).
	// Must work with a static (no Setup()) ToolLogic.
	// Must be overridden by tools that declare FeatureKeyExchange, FeatureKeyEncapsulation or FeatureSigning.
	GenerateKey(signet SignetInt) error

	// BurnKey deletes the loaded keys in the Signet.
	// Must work with a static (no Setup()) ToolLogic.
	// Must be overridden by tools that declare FeatureKeyExchange, FeatureKeyEncapsulation or FeatureSigning.
	// Implementations of this are currently ineffective, see known issues in the project's README.
	BurnKey(signet SignetInt) error

	// SecurityLevel returns the security level (approximate attack complexity as 2^n) of the given tool.
	// May be overridden if needed for custom calculation (ie. based on actual key size in signet or hash tool). Init() will be called before SecurityLevel() is called.
	SecurityLevel(signet SignetInt) (int, error)
}

ToolLogic is the uniform interface for all tools.

func New 

func New(name string) (ToolLogic, error)

New returns a new instance of a Tool's Logic with the given name.

type ToolLogicBase 

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

ToolLogicBase covers all methods of the ToolLogic interface with dummy implementations to reduce boilerplate code.

func (*ToolLogicBase) AuthenticatedDecrypt 

func (tlb *ToolLogicBase) AuthenticatedDecrypt(data, associatedData []byte) ([]byte, error)

AuthenticatedDecrypt implements the ToolLogic interface.

func (*ToolLogicBase) AuthenticatedEncrypt 

func (tlb *ToolLogicBase) AuthenticatedEncrypt(data, associatedData []byte) ([]byte, error)

AuthenticatedEncrypt implements the ToolLogic interface.

func (*ToolLogicBase) BurnKey 

func (tlb *ToolLogicBase) BurnKey(signet SignetInt) error

BurnKey implements the ToolLogic interface. This is currently ineffective, see known issues in the project's README.

func (*ToolLogicBase) Decrypt 

func (tlb *ToolLogicBase) Decrypt(data []byte) ([]byte, error)

Decrypt implements the ToolLogic interface.

func (*ToolLogicBase) Definition 

func (tlb *ToolLogicBase) Definition() *Tool

Definition returns Tool's definition. Do not override.

func (*ToolLogicBase) DeriveKey 

func (tlb *ToolLogicBase) DeriveKey(size int) ([]byte, error)

DeriveKey implements the ToolLogic interface.

func (*ToolLogicBase) DeriveKeyFromPassword 

func (tlb *ToolLogicBase) DeriveKeyFromPassword(password []byte, salt []byte) ([]byte, error)

DeriveKeyFromPassword implements the ToolLogic interface.

func (*ToolLogicBase) DeriveKeyWriteTo 

func (tlb *ToolLogicBase) DeriveKeyWriteTo(newKey []byte) error

DeriveKeyWriteTo implements the ToolLogic interface.

func (*ToolLogicBase) EncapsulateKey 

func (tlb *ToolLogicBase) EncapsulateKey(key []byte, remote SignetInt) ([]byte, error)

EncapsulateKey implements the ToolLogic interface.

func (*ToolLogicBase) Encrypt 

func (tlb *ToolLogicBase) Encrypt(data []byte) ([]byte, error)

Encrypt implements the ToolLogic interface.

func (*ToolLogicBase) Factory 

func (tlb *ToolLogicBase) Factory() ToolLogic

Factory returns a new instance of the ToolLogic. Do not override.

func (*ToolLogicBase) GenerateKey 

func (tlb *ToolLogicBase) GenerateKey(signet SignetInt) error

GenerateKey implements the ToolLogic interface.

func (*ToolLogicBase) HashTool 

func (tlb *ToolLogicBase) HashTool() *hashtools.HashTool

HashTool returns the assigned HashTool. Do not override.

func (*ToolLogicBase) Helper 

func (tlb *ToolLogicBase) Helper() HelperInt

Helper returns a Helper. Do not override.

func (*ToolLogicBase) Info 

func (tlb *ToolLogicBase) Info() *ToolInfo

Info returns information about the Tool. Do not override.

func (*ToolLogicBase) Init 

func (tlb *ToolLogicBase) Init(tool *Tool, helper HelperInt, hashTool *hashtools.HashTool, hashSumFn func() ([]byte, error))

Init is called by the internal tool initialized procedure and is called by NewTool(). Do not override.

func (*ToolLogicBase) InitKeyDerivation 

func (tlb *ToolLogicBase) InitKeyDerivation(nonce []byte, material ...[]byte) error

InitKeyDerivation implements the ToolLogic interface.

func (*ToolLogicBase) LoadKey 

func (tlb *ToolLogicBase) LoadKey(SignetInt) error

LoadKey implements the ToolLogic interface.

func (*ToolLogicBase) MAC 

func (tlb *ToolLogicBase) MAC(data, associatedData []byte) ([]byte, error)

MAC implements the ToolLogic interface.

func (*ToolLogicBase) MakeSharedKey 

func (tlb *ToolLogicBase) MakeSharedKey(local SignetInt, remote SignetInt) ([]byte, error)

MakeSharedKey implements the ToolLogic interface.

func (*ToolLogicBase) ManagedHashSum 

func (tlb *ToolLogicBase) ManagedHashSum() ([]byte, error)

ManagedHashSum returns the hashsum of the managed hasher. Must be enabled by the tool by declaring FeatureNeedsManagedHasher. Do not override.

func (*ToolLogicBase) Reset 

func (tlb *ToolLogicBase) Reset() error

Reset is called after all operations have finished and should be used to do cleanup and burn all key material. Override at will.

func (*ToolLogicBase) SecurityLevel 

func (tlb *ToolLogicBase) SecurityLevel(signet SignetInt) (int, error)

SecurityLevel returns the security level (approximate attack complexity as 2^n) of the given tool. May be overridden if needed for custom calculation (ie. based on actual key size in signet or hash tool). Init() will be called before SecurityLevel() is called.

func (*ToolLogicBase) Setup 

func (tlb *ToolLogicBase) Setup() error

Setup is called after Init and can be used the tool to do some custom setup before being used. Override at will. If a Tool needs key material, it needs to be requested here.

func (*ToolLogicBase) Sign 

func (tlb *ToolLogicBase) Sign(data, associatedData []byte, local SignetInt) ([]byte, error)

Sign implements the ToolLogic interface.

func (*ToolLogicBase) StoreKey 

func (tlb *ToolLogicBase) StoreKey(SignetInt) error

StoreKey implements the ToolLogic interface.

func (*ToolLogicBase) UnwrapKey 

func (tlb *ToolLogicBase) UnwrapKey(wrappedKey []byte, local SignetInt) ([]byte, error)

UnwrapKey implements the ToolLogic interface.

func (*ToolLogicBase) Verify 

func (tlb *ToolLogicBase) Verify(data, associatedData, signature []byte, remote SignetInt) error

Verify implements the ToolLogic interface.

Source Files

View all Source files

Directories

Path Synopsis
Package all imports all tool subpackages
 Package all imports all tool subpackages

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.