method

README

Encryption methods

[!WARNING] This file is not an end-user documentation, it is intended for developers. Please follow the user documentation on the OpenTofu website unless you want to work on the encryption code.

This folder contains the implementations for the encryption methods used in OpenTofu. Encryption methods determine how exactly data is encrypted, but they do not determine what exactly is encrypted.

Implementing a method

When you implement a method, take a look at the aesgcm method as a template.

Testing your method (do this first!)

Before you even go about writing a method, please set up the compliance tests. You can create a single test case that calls compliancetest.ComplianceTest. This test suite will run your key provider through all important compliance tests and will make sure that you are not missing anything during the implementation.

Implementing the descriptor

The descriptor is very simple, you need to implement the Descriptor interface in a type. (It does not have to be a struct.) However, make sure that the ConfigStruct always returns a struct with hcl tags on it. For more information on the hcl tags, see the gohcl documentation.

The config struct

Next, you need to create a config structure. This structure should hold all the fields you expect a user to fill out. This must be a struct, and you must add hcl tags to each field you expect the user to fill out.

If the config structure needs input from key providers, it should declare one HCL-tagged field with the type of keyprovider.Output to receive the encryption and decryption key. Note, that the decryption key is not always available.

Additionally, you must implement the Build function described in the Config interface. You can take a look at aesgcm/config.go for an example on implementing this.

The method

The heart of your method is... well, your method. It has the Encrypt() and Decrypt() methods, which should perform the named tasks. If no decryption key is available, the method should refuse to decrypt data. The method should under no circumstances pass through unencrypted data if it fails to decrypt the data.

Documentation

Index

• type Addr
  • func NewAddr(method string, name string) (addr Addr, err hcl.Diagnostics)
  • func (a Addr) Validate() hcl.Diagnostics
• type Config
• type Descriptor
• type ErrCryptoFailure
  • func (e ErrCryptoFailure) Error() string
  • func (e ErrCryptoFailure) Unwrap() error
• type ErrDecryptionFailed
  • func (e ErrDecryptionFailed) Error() string
  • func (e ErrDecryptionFailed) Unwrap() error
• type ErrDecryptionKeyUnavailable
  • func (e ErrDecryptionKeyUnavailable) Error() string
• type ErrEncryptionFailed
  • func (e ErrEncryptionFailed) Error() string
  • func (e ErrEncryptionFailed) Unwrap() error
• type ErrInvalidConfiguration
  • func (e ErrInvalidConfiguration) Error() string
  • func (e ErrInvalidConfiguration) Unwrap() error
• type ID
  • func (i ID) Validate() error
• type Method

Types

type Addr

type Addr string

Addr is a type-alias for method address strings that identify a specific encryption method configuration. The Addr is an opaque value. Do not perform string manipulation on it outside the functions supplied by the method package.

func NewAddr

func NewAddr(method string, name string) (addr Addr, err hcl.Diagnostics)

NewAddr creates a new Addr type from the provider and name supplied. The Addr is a type-alias for encryption method address strings that identify a specific encryption method configuration. You should treat the value as opaque and not perform string manipulation on it outside the functions supplied by the method package.

func (Addr) Validate

func (a Addr) Validate() hcl.Diagnostics

Validate validates the Addr for formal naming conformance, but does not check if the referenced method actually exists in the configuration.

type Config

type Config interface {
	// Build takes the configuration and builds an encryption method.
	// TODO this may be better changed to return hcl.Diagnostics so warnings can be issued?
	Build() (Method, error)
}

Config describes a configuration struct for setting up an encryption Method. You should always implement this interface with a struct, and you should tag the fields with HCL tags so the encryption implementation can read the .tf code into it. For example:

type MyConfig struct {
    Key string `hcl:"key"`
}

func (m MyConfig) Build() (Method, error) { ... }

type Descriptor

type Descriptor interface {
	// ID returns the unique identifier used when parsing HCL or JSON configs.
	ID() ID

	// ConfigStruct creates a new configuration struct annotated with hcl tags. The Build() receiver on
	// this struct must be able to build a Method from the configuration.
	//
	// Common errors:
	// - Returning a struct without a pointer
	// - Returning a non-struct
	ConfigStruct() Config
}

Descriptor contains the details on an encryption method and produces a configuration structure with default values.

type ErrCryptoFailure

type ErrCryptoFailure struct {
	Message string
	Cause   error
}

ErrCryptoFailure indicates a generic cryptographic failure. This error should be embedded into ErrEncryptionFailed, ErrDecryptionFailed, or ErrInvalidConfiguration.

func (ErrCryptoFailure) Error

func (e ErrCryptoFailure) Error() string

func (ErrCryptoFailure) Unwrap

func (e ErrCryptoFailure) Unwrap() error

type ErrDecryptionFailed

type ErrDecryptionFailed struct {
	Cause error
}

ErrDecryptionFailed indicates that decrypting a set of data failed.

func (ErrDecryptionFailed) Error

func (e ErrDecryptionFailed) Error() string

func (ErrDecryptionFailed) Unwrap

func (e ErrDecryptionFailed) Unwrap() error

type ErrDecryptionKeyUnavailable

type ErrDecryptionKeyUnavailable struct {
}

ErrDecryptionKeyUnavailable indicates that no decryption key is available.

func (ErrDecryptionKeyUnavailable) Error

func (e ErrDecryptionKeyUnavailable) Error() string

type ErrEncryptionFailed

type ErrEncryptionFailed struct {
	Cause error
}

ErrEncryptionFailed indicates that encrypting a set of data failed.

func (ErrEncryptionFailed) Error

func (e ErrEncryptionFailed) Error() string

func (ErrEncryptionFailed) Unwrap

func (e ErrEncryptionFailed) Unwrap() error

type ErrInvalidConfiguration

type ErrInvalidConfiguration struct {
	Cause error
}

ErrInvalidConfiguration indicates that the method configuration is incorrect.

func (ErrInvalidConfiguration) Error

func (e ErrInvalidConfiguration) Error() string

func (ErrInvalidConfiguration) Unwrap

func (e ErrInvalidConfiguration) Unwrap() error

type ID

type ID string

ID is a type alias to make passing the wrong ID into a method ID harder.

func (ID) Validate

func (i ID) Validate() error

Validate validates the key provider ID for correctness.

type Method

type Method interface {
	// Encrypt encrypts the specified data with the set configuration. This method should treat any data passed as
	// opaque and should not try to interpret its contents. The interpretation is the job of the encryption.Encryption
	// interface.
	Encrypt(data []byte) ([]byte, error)
	// Decrypt decrypts the specified data with the set configuration. This method should treat any data passed as
	// opaque and should not try to interpret its contents. The interpretation is the job of the encryption.Encryption
	// interface.
	Decrypt(data []byte) ([]byte, error)
}

Method is a low-level encryption method interface that is responsible for encrypting a binary blob of data. It should not try to interpret what kind of data it is encrypting.