kms

Documentation

Index

• Constants
• type Config
• type Context
  • func (c Context) MarshalText() ([]byte, error)
• type DEK
  • func (d DEK) MarshalText() ([]byte, error)
  • func (d *DEK) UnmarshalText(text []byte) error
• type Error
  • func (e Error) Error() string
• type IdentityManager
• type KMS
  • func New(keyID string, key []byte) (KMS, error)
  • func NewWithConfig(config Config) (KMS, error)
  • func Parse(s string) (KMS, error)
• type KeyManager
• type PolicyManager
• type Status
• type StatusManager
• type VerifyResult

Constants

const (
	EnvKMSSecretKey      = "MINIO_KMS_SECRET_KEY"
	EnvKMSSecretKeyFile  = "MINIO_KMS_SECRET_KEY_FILE"
	EnvKESEndpoint       = "MINIO_KMS_KES_ENDPOINT"     // One or multiple KES endpoints, separated by ','
	EnvKESEnclave        = "MINIO_KMS_KES_ENCLAVE"      // Optional "namespace" within a KES cluster - not required for stateless KES
	EnvKESKeyName        = "MINIO_KMS_KES_KEY_NAME"     // The default key name used for IAM data and when no key ID is specified on a bucket
	EnvKESAPIKey         = "MINIO_KMS_KES_API_KEY"      // Access credential for KES - API keys and private key / certificate are mutually exclusive
	EnvKESClientKey      = "MINIO_KMS_KES_KEY_FILE"     // Path to TLS private key for authenticating to KES with mTLS - usually prefer API keys
	EnvKESClientPassword = "MINIO_KMS_KES_KEY_PASSWORD" // Optional password to decrypt an encrypt TLS private key
	EnvKESClientCert     = "MINIO_KMS_KES_CERT_FILE"    // Path to TLS certificate for authenticating to KES with mTLS - usually prefer API keys
	EnvKESServerCA       = "MINIO_KMS_KES_CAPATH"       // Path to file/directory containing CA certificates to verify the KES server certificate
)

Top level config constants for KMS

Types

type Config

type Config struct {
	// Endpoints contains a list of KMS server
	// HTTP endpoints.
	Endpoints []string

	// Enclave is the KES server enclave. If empty,
	// none resp. the default KES server enclave
	// will be used.
	Enclave string

	// DefaultKeyID is the key ID used when
	// no explicit key ID is specified for
	// a cryptographic operation.
	DefaultKeyID string

	// APIKey is an credential provided by env. var.
	// to authenticate to a KES server. Either an
	// API key or a client certificate must be specified.
	APIKey kes.APIKey

	// Certificate is the client TLS certificate
	// to authenticate to KMS via mTLS.
	Certificate *certs.Certificate

	// ReloadCertEvents is an event channel that receives
	// the reloaded client certificate.
	ReloadCertEvents <-chan tls.Certificate

	// RootCAs is a set of root CA certificates
	// to verify the KMS server TLS certificate.
	RootCAs *x509.CertPool
}

Config contains various KMS-related configuration parameters - like KMS endpoints or authentication credentials.

type Context

type Context map[string]string

Context is a set of key-value pairs that are associated with a generate data encryption key (DEK).

A KMS implementation may bind the context to the generated DEK such that the same context must be provided when decrypting an encrypted DEK.

func (Context) MarshalText

func (c Context) MarshalText() ([]byte, error)

MarshalText sorts the context keys and writes the sorted key-value pairs as canonical JSON object. The sort order is based on the un-escaped keys. It never returns an error.

type DEK

type DEK struct {
	KeyID      string
	Plaintext  []byte
	Ciphertext []byte
}

DEK is a data encryption key. It consists of a plaintext-ciphertext pair and the ID of the key used to generate the ciphertext.

The plaintext can be used for cryptographic operations - like encrypting some data. The ciphertext is the encrypted version of the plaintext data and can be stored on untrusted storage.

func (DEK) MarshalText

func (d DEK) MarshalText() ([]byte, error)

MarshalText encodes the DEK's key ID and ciphertext as JSON.

func (*DEK) UnmarshalText

func (d *DEK) UnmarshalText(text []byte) error

UnmarshalText tries to decode text as JSON representation of a DEK and sets DEK's key ID and ciphertext to the decoded values.

It sets DEK's plaintext to nil.

type Error

type Error struct {
	Err            error
	APICode        string
	HTTPStatusCode int
}

Error encapsulates S3 API error response fields.

func (Error) Error

func (e Error) Error() string

type IdentityManager

type IdentityManager interface {
	// DescribeIdentity describes an identity by returning its metadata.
	// e.g. which policy is currently assigned and whether its an admin identity.
	DescribeIdentity(ctx context.Context, identity string) (*kes.IdentityInfo, error)

	// DescribeSelfIdentity describes the identity issuing the request.
	// It infers the identity from the TLS client certificate used to authenticate.
	// It returns the identity and policy information for the client identity.
	DescribeSelfIdentity(ctx context.Context) (*kes.IdentityInfo, *kes.Policy, error)

	// 	DeleteIdentity deletes an identity from KMS.
	// The client certificate that corresponds to the identity is no longer authorized to perform any API operations.
	// The admin identity cannot be deleted.
	DeleteIdentity(ctx context.Context, identity string) error

	// ListIdentities lists all identities.
	ListIdentities(ctx context.Context) (*kes.ListIter[kes.Identity], error)
}

IdentityManager is the generic interface that handles KMS identity operations

type KMS

type KMS interface {
	// Stat returns the current KMS status.
	Stat(cxt context.Context) (Status, error)

	// IsLocal returns true if the KMS is a local implementation
	IsLocal() bool

	// List returns an array of local KMS Names
	List() []kes.KeyInfo

	// Metrics returns a KMS metric snapshot.
	Metrics(ctx context.Context) (kes.Metric, error)

	// CreateKey creates a new key at the KMS with the given key ID.
	CreateKey(ctx context.Context, keyID string) error

	// GenerateKey generates a new data encryption key using the
	// key referenced by the key ID.
	//
	// The KMS may use a default key if the key ID is empty.
	// GenerateKey returns an error if the referenced key does
	// not exist.
	//
	// The context is associated and tied to the generated DEK.
	// The same context must be provided when the generated key
	// should be decrypted. Therefore, it is the callers
	// responsibility to remember the corresponding context for
	// a particular DEK. The context may be nil.
	GenerateKey(ctx context.Context, keyID string, context Context) (DEK, error)

	// DecryptKey decrypts the ciphertext with the key referenced
	// by the key ID. The context must match the context value
	// used to generate the ciphertext.
	DecryptKey(keyID string, ciphertext []byte, context Context) ([]byte, error)

	// DecryptAll decrypts all ciphertexts with the key referenced
	// by the key ID. The contexts must match the context value
	// used to generate the ciphertexts.
	DecryptAll(ctx context.Context, keyID string, ciphertext [][]byte, context []Context) ([][]byte, error)

	// Verify verifies all KMS endpoints and returns the details
	Verify(cxt context.Context) []VerifyResult
}

KMS is the generic interface that abstracts over different KMS implementations.

func New

func New(keyID string, key []byte) (KMS, error)

New returns a single-key KMS that derives new DEKs from the given key.

func NewWithConfig

func NewWithConfig(config Config) (KMS, error)

NewWithConfig returns a new KMS using the given configuration.

func Parse

func Parse(s string) (KMS, error)

Parse parses s as single-key KMS. The given string is expected to have the following format:

<key-id>:<base64-key>

The returned KMS implementation uses the parsed key ID and key to derive new DEKs and decrypt ciphertext.

type KeyManager

type KeyManager interface {
	// CreateKey creates a new key at the KMS with the given key ID.
	CreateKey(ctx context.Context, keyID string) error

	// DeleteKey deletes a key at the KMS with the given key ID.
	// Please note that is a dangerous operation.
	// Once a key has been deleted all data that has been encrypted with it cannot be decrypted
	// anymore, and therefore, is lost.
	DeleteKey(ctx context.Context, keyID string) error

	// ListKeys lists all key names.
	ListKeys(ctx context.Context) (*kes.ListIter[string], error)

	// ImportKey imports a cryptographic key into the KMS.
	ImportKey(ctx context.Context, keyID string, bytes []byte) error

	// EncryptKey Encrypts and authenticates a (small) plaintext with the cryptographic key
	// The plaintext must not exceed 1 MB
	EncryptKey(keyID string, plaintext []byte, context Context) ([]byte, error)
}

KeyManager is the generic interface that handles KMS key operations

type PolicyManager

type PolicyManager interface {
	// DescribePolicy describes a policy by returning its metadata.
	// e.g. who created the policy at which point in time.
	DescribePolicy(ctx context.Context, policy string) (*kes.PolicyInfo, error)

	// AssignPolicy assigns a policy to an identity.
	// An identity can have at most one policy while the same policy can be assigned to multiple identities.
	// The assigned policy defines which API calls this identity can perform.
	// It's not possible to assign a policy to the admin identity.
	// Further, an identity cannot assign a policy to itself.
	AssignPolicy(ctx context.Context, policy, identity string) error

	// GetPolicy gets a policy from KMS.
	GetPolicy(ctx context.Context, policy string) (*kes.Policy, error)

	// ListPolicies lists all policies.
	ListPolicies(ctx context.Context) (*kes.ListIter[string], error)

	// DeletePolicy	deletes a policy from KMS.
	// All identities that have been assigned to this policy will lose all authorization privileges.
	DeletePolicy(ctx context.Context, policy string) error
}

PolicyManager is the generic interface that handles KMS policy] operations

type Status

type Status struct {
	Name      string   // The name of the KMS
	Endpoints []string // A set of the KMS endpoints

	// DefaultKey is the key used when no explicit key ID
	// is specified. It is empty if the KMS does not support
	// a default key.
	DefaultKey string

	// Details provides more details about the KMS endpoint status.
	// including uptime, version and available CPUs.
	// Could be more in future.
	Details kes.State
}

Status describes the current state of a KMS.

type StatusManager

type StatusManager interface {
	// Version retrieves version information
	Version(ctx context.Context) (string, error)
	// APIs retrieves a list of supported API endpoints
	APIs(ctx context.Context) ([]kes.API, error)
}

StatusManager is the generic interface that handles KMS status operations

type VerifyResult

type VerifyResult struct {
	Endpoint string
	Decrypt  string
	Encrypt  string
	Version  string
	Status   string
}

VerifyResult describes the verification result details a KMS endpoint