api

type BackupKeystore interface {
	KeyStore
	// ImportKeyRings unpacks key rings packaged by ExportKeyRings.
	// The provided cryptosuite is used to verify the signature on the container and decrypt key ring data.
	// Optional delegate can be used to control various aspects of the import process, such as conflict resolution.
	// Returns a list of processed key rings.
	ImportKeyRings(exportData []byte, cryptosuite *crypto.KeyStoreSuite, delegate KeyRingImportDelegate) ([]string, error)
}

type ImportDecision int

type KeyData struct {
	Format       KeyFormat
	PublicKey    []byte
	PrivateKey   []byte
	SymmetricKey []byte
}

type KeyDescription struct {
	ValidSince time.Time
	ValidUntil time.Time
	Data       []KeyData
}

type KeyFormat int

type KeyRing interface {
	// CurrentKey returns the key that you should currently use.
	CurrentKey() (int, error)

	// AllKeys returns all keys in the key ring, from newest to oldest.
	AllKeys() ([]int, error)

	// State of the key right now.
	State(seqnum int) (KeyState, error)

	// ValidSince returns the time before which the key cannot be used.
	ValidSince(seqnum int) (time.Time, error)
	// ValidUntil returns the time since which the key should not be used.
	ValidUntil(seqnum int) (time.Time, error)

	// Formats available for this key.
	Formats(seqnum int) ([]KeyFormat, error)
	// PublicKey data in given format, if available.
	PublicKey(seqnum int, format KeyFormat) ([]byte, error)
	// PrivateKey data in given format, if available.
	PrivateKey(seqnum int, format KeyFormat) ([]byte, error)
	// SymmetricKey data in given format, if available.
	SymmetricKey(seqnum int, format KeyFormat) ([]byte, error)
}

type KeyRingImportDelegate interface {
	// This method is executed when an imported key ring already exists.
	// Current key ring content is encrypted, new key ring content is in plain.
	// Don't look at the key material, decide based on validity ranges and sequence numbers.
	DecideKeyRingOverwrite(currentData, newData *asn1.KeyRing) (ImportDecision, error)
}

type KeyState int

type KeyStore interface {
	// OpenKeyRing opens an existing key ring with given purpose.
	OpenKeyRing(purpose string) (KeyRing, error)

	// Close this keystore, releasing associated resources.
	// This generally renders opened KeyRings unusable.
	Close() error

	// ListKeyRings enumerates all key rings present in this keystore.
	ListKeyRings() ([]string, error)

	// ExportKeyRings packages specified key rings for export.
	// Key ring data is encrypted and signed using given cryptosuite.
	// Resulting container can be imported into existing or different keystore with ImportKeyRings().
	ExportKeyRings(paths []string, cryptosuite *crypto.KeyStoreSuite, mode keystoreV1.ExportMode) ([]byte, error)

	// DescribeKeyRing describes key ring by its purpose path.
	DescribeKeyRing(purpose string) (*keystoreV1.KeyDescription, error)

	// DescribeRotatedKeyRing describes rotated key ring bys its purpose path.
	DescribeRotatedKeyRing(path string) ([]keystoreV1.KeyDescription, error)
}

type MutableKeyRing interface {
	KeyRing

	// AddKey attaches a new key to the ring.
	AddKey(key KeyDescription) (int, error)

	// SetState changes key State to the given one, if allowed.
	SetState(seqnum int, newState KeyState) error

	// DestroyKey erases key data (but keeps the key in the ring).
	DestroyKey(seqnum int) error

	// SetCurrent makes this key current in its key ring.
	// Does nothing if the key is already current.
	SetCurrent(seqnum int) error
}

type MutableKeyStore interface {
	KeyStore

	// OpenKeyRingRW opens a modifiable key ring with given purpose.
	// A new key ring will be created if it does not exist yet.
	OpenKeyRingRW(purpose string) (MutableKeyRing, error)

	// ImportKeyRings unpacks key rings packaged by ExportKeyRings.
	// The provided cryptosuite is used to verify the signature on the container and decrypt key ring data.
	// Optional delegate can be used to control various aspects of the import process, such as conflict resolution.
	// Returns a list of processed key rings.
	ImportKeyRings(exportData []byte, cryptosuite *crypto.KeyStoreSuite, delegate KeyRingImportDelegate) ([]string, error)
}