encryption

type CryptographyEngine interface {

	/*
		KEKID the ID of the primary RSA key pair this engine is configured with

			@returns the key pair ID
	*/
	KEKID() string

	/*
		LoadKEK load a primary RSA key pair without adopting it

		The engine keeps the key pair it was constructed with. A KEK rotation needs a second
		one to wrap with, while the first stays in place to unwrap the keys not yet converted.

			@param ctx context.Context - execution context
			@param params KEKParams - the key pair file paths
			@returns the loaded key pair
	*/
	LoadKEK(ctx context.Context, params KEKParams) (KEK, error)

	/*
	   NewEncryptionKey define a new encryption symmetric encryption key

	   	@param ctx context.Context - execution context
	   	@param activeDBClient Database - existing database transaction
	   	@returns the key entry
	*/
	NewEncryptionKey(ctx context.Context, activeDBClient db.Database) (models.EncryptionKey, error)

	/*
		GetEncryptionKey fetch one encryption key

		Served from the key cache when a fresh entry exists; otherwise read from persistence.

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
			@param activeDBClient Database - existing database transaction
			@return key entry
	*/
	GetEncryptionKey(
		ctx context.Context, keyID string, activeDBClient db.Database,
	) (models.EncryptionKey, error)

	/*
		ListEncryptionKeys list encryption keys

			@param ctx context.Context - execution context
			@param filters EncryptionKeyQueryFilter - entry listing filter
			@param activeDBClient Database - existing database transaction
			@return list of keys
	*/
	ListEncryptionKeys(
		ctx context.Context, filters db.EncryptionKeyQueryFilter, activeDBClient db.Database,
	) ([]models.EncryptionKey, error)

	/*
		EncryptData encrypt plain text

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
			@param plainText []byte - the plain text to encrypt
			@param additional []byte - associated data authenticated with, but not included in,
			    the cipher text. The identical value must be supplied to decrypt. Optional.
			@param activeDBClient Database - existing database transaction
			@return key entry for the encryption, and the cipher text
	*/
	EncryptData(
		ctx context.Context,
		keyID string,
		plainText []byte,
		additional []byte,
		activeDBClient db.Database,
	) (models.EncryptionKey, EncryptedData, error)

	/*
		DecryptData decrypt cipher text

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
			@param encrypted EncryptedData - the cipher text to decrypt
			@param additional []byte - the associated data supplied when encrypting
			@param activeDBClient Database - existing database transaction
			@return key entry for the encryption, and the plain text
	*/
	DecryptData(
		ctx context.Context,
		keyID string,
		encrypted EncryptedData,
		additional []byte,
		activeDBClient db.Database,
	) (models.EncryptionKey, []byte, error)

	/*
		ReEncryptRecordVersions move record versions onto a different encryption key

		Each version is decrypted under the key which currently holds it, and re-sealed under
		the target key with a fresh nonce and the associated data recomputed from the new key
		ID. The version keeps its ID, its record and its place in the record's history; only
		the encryption columns change.

		Halts on the first version which will not decrypt, returning an UndecryptableVersion
		and converting nothing further.

			@param ctx context.Context - execution context
			@param versions []models.RecordVersion - the versions to move
			@param targetKey models.EncryptionKey - the key to move them onto
			@param activeDBClient Database - existing database transaction
	*/
	ReEncryptRecordVersions(
		ctx context.Context,
		versions []models.RecordVersion,
		targetKey models.EncryptionKey,
		activeDBClient db.Database,
	) error

	/*
		FindUndecryptableVersions report which record versions will not decrypt

		Read only: it attempts to decrypt each version and converts nothing. This sizes the
		damage after ReEncryptRecordVersions halts, so an operator can choose between
		restoring the rows from a backup and destroying them.

			@param ctx context.Context - execution context
			@param versions []models.RecordVersion - the versions to check
			@param activeDBClient Database - existing database transaction
			@returns one finding per version which failed to decrypt
	*/
	FindUndecryptableVersions(
		ctx context.Context,
		versions []models.RecordVersion,
		activeDBClient db.Database,
	) ([]UndecryptableVersion, error)

	/*
		RewrapEncryptionKeys re-wrap encryption keys under a different primary RSA key pair

		Each key's material is unwrapped with the key pair this engine holds and re-wrapped
		under the given one. The symmetric key itself is unchanged, so every record version
		encrypted with it stays valid and none are touched.

		Keys already carrying the new key pair's ID are skipped, which is what lets an
		interrupted KEK rotation resume.

			@param ctx context.Context - execution context
			@param keys []models.EncryptionKey - the keys to re-wrap
			@param newKEK KEK - the key pair to re-wrap them under
			@param activeDBClient Database - existing database transaction
	*/
	RewrapEncryptionKeys(
		ctx context.Context,
		keys []models.EncryptionKey,
		newKEK KEK,
		activeDBClient db.Database,
	) error
}

type CryptographyEngineParams struct {
	// Persistence persistence layer client
	Persistence db.Client `validate:"-"`
	// PrimaryRSACertFile file path to the primary RSA certificate PEM
	PrimaryRSACertFile string `validate:"required,file"`
	// PrimaryRSAKeyFile file path to the primary RSA certificate private key PEM
	PrimaryRSAKeyFile string `validate:"required,file"`
	// PrimaryRSACACertFile file path to a PEM bundle of the CA certificates that issued the
	// primary RSA certificate. When set, the certificate must chain to a self-signed root in
	// the bundle through any intermediates the bundle also holds. When nil, only the
	// certificate's validity window is checked. Revocation is never checked.
	PrimaryRSACACertFile *string `validate:"omitempty,file"`
	// KeyCacheTTL how long a cached encryption key is trusted before it is re-validated
	// against persistence. 0 re-validates on every use.
	KeyCacheTTL time.Duration `validate:"gte=0"`
}

type EncryptedData struct {
	// CipherText the cipher text
	CipherText []byte
	// Nonce the nonce
	Nonce []byte
}

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

type KEKParams struct {
	// CertFile file path to the RSA certificate PEM
	CertFile string `validate:"required,file"`
	// KeyFile file path to the RSA certificate private key PEM
	KeyFile string `validate:"required,file"`
	// CACertFile file path to a PEM bundle of the CA certificates that issued the
	// certificate. When set, the certificate must chain to a self-signed root in the bundle
	// through any intermediates the bundle also holds. When nil, only the certificate's
	// validity window is checked. Revocation is never checked.
	CACertFile *string `validate:"omitempty,file"`
}

type UndecryptableVersion struct {
	// Version the record version as it was read
	Version models.RecordVersion
	// Cause the underlying authentication failure
	Cause error
}