tools

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
}

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
}

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
}

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
}

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)
}

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