kms

package
v0.0.0-...-534e716 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2024 License: AGPL-3.0 Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EnvKMSEndpoint   = "MINIO_KMS_SERVER"  // List of MinIO KMS endpoints, separated by ','
	EnvKMSEnclave    = "MINIO_KMS_ENCLAVE" // MinIO KMS enclave in which the key and identity exists
	EnvKMSDefaultKey = "MINIO_KMS_SSE_KEY" // Default key used for SSE-S3 or when no SSE-KMS key ID is specified
	EnvKMSAPIKey     = "MINIO_KMS_API_KEY" // Credential to access the MinIO KMS.
)

Environment variables for MinIO KMS.

View Source 
const (
	EnvKESEndpoint       = "MINIO_KMS_KES_ENDPOINT"     // One or multiple KES endpoints, separated by ','
	EnvKESDefaultKey     = "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
	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
	EnvKESClientPassword = "MINIO_KMS_KES_KEY_PASSWORD" // Optional password to decrypt an encrypt TLS private key
)

Environment variables for MinIO KES.

View Source 
const (
	EnvKMSSecretKey     = "MINIO_KMS_SECRET_KEY"      // Static KMS key in the form "<key-name>:<base64-32byte-key>". Implements a subset of KMS/KES APIs
	EnvKMSSecretKeyFile = "MINIO_KMS_SECRET_KEY_FILE" // Path to a file to read the static KMS key from
)

Environment variables for static KMS key.

Variables

View Source 
var (
	// ErrPermission is an error returned by the KMS when it has not
	// enough permissions to perform the operation.
	ErrPermission = Error{
		Code:    http.StatusForbidden,
		APICode: "kms:NotAuthorized",
		Err:     "insufficient permissions to perform KMS operation",
	}

	// ErrKeyExists is an error returned by the KMS when trying to
	// create a key that already exists.
	ErrKeyExists = Error{
		Code:    http.StatusConflict,
		APICode: "kms:KeyAlreadyExists",
		Err:     "key with given key ID already exits",
	}

	// ErrKeyNotFound is an error returned by the KMS when trying to
	// use a key that does not exist.
	ErrKeyNotFound = Error{
		Code:    http.StatusNotFound,
		APICode: "kms:KeyNotFound",
		Err:     "key with given key ID does not exit",
	}

	// ErrDecrypt is an error returned by the KMS when the decryption
	// of a ciphertext failed.
	ErrDecrypt = Error{
		Code:    http.StatusBadRequest,
		APICode: "kms:InvalidCiphertextException",
		Err:     "failed to decrypt ciphertext",
	}

	// ErrNotSupported is an error returned by the KMS when the requested
	// functionality is not supported by the KMS service.
	ErrNotSupported = Error{
		Code:    http.StatusNotImplemented,
		APICode: "kms:NotSupported",
		Err:     "requested functionality is not supported",
	}
)

Functions

func IsPresent 

func IsPresent() (bool, error)

IsPresent reports whether a KMS configuration is present. It returns an error if multiple KMS configurations are present or if one configuration is incomplete.

Types

type ConnectionOptions 

type ConnectionOptions struct {
	CADir string // Path to directory (or file) containing CA certificates
}

ConnectionOptions is a structure containing options for connecting to a KMS.

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 CreateKeyRequest 

type CreateKeyRequest struct {
	// Name is the name of the key that gets created.
	Name string
}

CreateKeyRequest is a structure containing fields and options for creating keys.

type DEK 

type DEK struct {
	KeyID      string // Name of the master key
	Version    int    // Version of the master key (MinKMS only)
	Plaintext  []byte // Paintext of the data encryption key
	Ciphertext []byte // Ciphertext of the data encryption key
}

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 DecryptRequest 

type DecryptRequest struct {
	// Name is the name of the master key used decrypt
	// the ciphertext.
	Name string

	// Version is the version of the master used for
	// decryption. If empty, the latest key version
	// is used.
	Version int

	// Ciphertext is the encrypted data that gets
	// decrypted.
	Ciphertext []byte

	// AssociatedData is the crypto. associated data.
	// It must match the data used during encryption
	// or data key generation.
	AssociatedData Context
}

DecryptRequest is a structure containing fields and options for decrypting data.

type DeleteKeyRequest 

type DeleteKeyRequest struct {
	// Name is the name of the key that gets deleted.
	Name string
}

DeleteKeyRequest is a structure containing fields and options for deleting keys.

type Error 

type Error struct {
	Code    int    // The HTTP status code returned to the client
	APICode string // The API error code identifying the error
	Err     string // The error message returned to the client
	Cause   error  // Optional, lower level error cause.
}

Error is a KMS error that can be translated into an S3 API error.

It does not implement the standard error Unwrap interface for better error log messages.

func (Error) Error 

func (e Error) Error() string

type GenerateKeyRequest 

type GenerateKeyRequest struct {
	// Name is the name of the master key used to generate
	// the data key.
	Name string

	// AssociatedData is optional data that is cryptographically
	// associated with the generated data key. The same data
	// must be provided when decrypting an encrypted data key.
	//
	// Typically, associated data is some metadata about the
	// data key. For example, the name of the object for which
	// the data key is used.
	AssociatedData Context
}

GenerateKeyRequest is a structure containing fields and options for generating data keys.

type KMS 

type KMS struct {
	// Type identifies the KMS implementation. Either,
	// MinKMS, MinKES or Builtin.
	Type Type

	// The default key, used for generating new data keys
	// if no explicit GenerateKeyRequest.Name is provided.
	DefaultKey string
	// contains filtered or unexported fields
}

KMS is a connection to a key management system. It implements various cryptographic operations, like data key generation and decryption.

func Connect 

func Connect(ctx context.Context, opts *ConnectionOptions) (*KMS, error)

Connect returns a new Conn to a KMS. It uses configuration from the environment and returns a:

  • connection to MinIO KMS if the "MINIO_KMS_SERVER" variable is present.
  • connection to MinIO KES if the "MINIO_KMS_KES_ENDPOINT" is present.
  • connection to a "local" KMS implementation using a static key if the "MINIO_KMS_SECRET_KEY" or "MINIO_KMS_SECRET_KEY_FILE" is present.

It returns an error if connecting to the KMS implementation fails, e.g. due to incomplete config, or when configurations for multiple KMS implementations are present.

func NewBuiltin 

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

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

func ParseSecretKey 

func ParseSecretKey(s string) (*KMS, error)

ParseSecretKey parses s as <key-id>:<base64> and returns a KMS that uses s as builtin single key as KMS implementation.

func (*KMS) APIs 

func (k *KMS) APIs(ctx context.Context) ([]madmin.KMSAPI, error)

APIs returns a list of KMS server APIs.

TODO(aead): remove this API since it's hardly useful.

func (*KMS) CreateKey 

func (k *KMS) CreateKey(ctx context.Context, req *CreateKeyRequest) error

CreateKey creates the master key req.Name. It returns ErrKeyExists if the key already exists.

func (*KMS) Decrypt 

func (k *KMS) Decrypt(ctx context.Context, req *DecryptRequest) ([]byte, error)

Decrypt decrypts a ciphertext using the master key req.Name. It returns ErrKeyNotFound if the key does not exist.

func (*KMS) GenerateKey 

func (k *KMS) GenerateKey(ctx context.Context, req *GenerateKeyRequest) (DEK, error)

GenerateKey generates a new data key using the master key req.Name. It returns ErrKeyNotFound if the key does not exist. If req.Name is empty, the KMS default key is used.

func (*KMS) ListKeyNames 

func (k *KMS) ListKeyNames(ctx context.Context, req *ListRequest) ([]string, string, error)

ListKeyNames returns a list of key names and a potential next name from where to continue a subsequent listing.

func (*KMS) MAC 

func (k *KMS) MAC(ctx context.Context, req *MACRequest) ([]byte, error)

MAC generates the checksum of the given req.Message using the key with the req.Name at the KMS.

func (*KMS) Metrics 

func (k *KMS) Metrics(ctx context.Context) (*Metrics, error)

Metrics returns a current snapshot of the KMS metrics.

func (*KMS) Status 

func (k *KMS) Status(ctx context.Context) (*madmin.KMSStatus, error)

Status returns status information about the KMS.

TODO(aead): refactor this API call since it does not account for multiple KMS/KES servers.

func (*KMS) Version 

func (k *KMS) Version(ctx context.Context) (string, error)

Version returns version information about the KMS.

TODO(aead): refactor this API call since it does not account for multiple KMS/KES servers.

type ListRequest 

type ListRequest struct {
	// Prefix is an optional prefix for filtering names.
	// A list operation only returns elements that match
	// this prefix.
	// An empty prefix matches any value.
	Prefix string

	// ContinueAt is the name of the element from where
	// a listing should continue. It allows paginated
	// listings.
	ContinueAt string

	// Limit limits the number of elements returned by
	// a single list operation. If <= 0, a reasonable
	// limit is selected automatically.
	Limit int
}

ListRequest is a structure containing fields and options for listing keys.

type MACRequest 

type MACRequest struct {
	// Name is the name of the master key used decrypt
	// the ciphertext.
	Name string

	Version int

	Message []byte
}

MACRequest is a structure containing fields and options for generating message authentication codes (MAC).

type Metrics 

type Metrics struct {
	ReqOK   uint64                   `json:"kms_req_success"` // Number of requests that succeeded
	ReqErr  uint64                   `json:"kms_req_error"`   // Number of requests that failed with a defined error
	ReqFail uint64                   `json:"kms_req_failure"` // Number of requests that failed with an undefined error
	Latency map[time.Duration]uint64 `json:"kms_resp_time"`   // Latency histogram of all requests
}

Metrics is a structure containing KMS metrics.

type Status 

type Status struct {
	Online  map[string]struct{}
	Offline map[string]Error
}

Status describes the current state of a KMS.

type Type 

type Type uint

Type identifies the KMS type. 

const (
	MinKMS  Type = iota + 1 // MinIO KMS
	MinKES                  // MinIO MinKES
	Builtin                 // Builtin single key KMS implementation
)

Supported KMS types

func (Type) String 

func (t Type) String() string

String returns the Type's string representation

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.