Documentation
¶
Index ¶
- Constants
- Variables
- func IsPresent() (bool, error)
- func ReplicateKeyID() bool
- type ConnectionOptions
- type Context
- type CreateKeyRequest
- type DEK
- type DecryptRequest
- type DeleteKeyRequest
- type Error
- type GenerateKeyRequest
- type KMS
- func (k *KMS) APIs(ctx context.Context) ([]madmin.KMSAPI, error)
- func (k *KMS) CreateKey(ctx context.Context, req *CreateKeyRequest) error
- func (k *KMS) Decrypt(ctx context.Context, req *DecryptRequest) ([]byte, error)
- func (k *KMS) GenerateKey(ctx context.Context, req *GenerateKeyRequest) (DEK, error)
- func (k *KMS) ListKeys(ctx context.Context, req *ListRequest) ([]madmin.KMSKeyInfo, string, error)
- func (k *KMS) MAC(ctx context.Context, req *MACRequest) ([]byte, error)
- func (k *KMS) Metrics(ctx context.Context) (*Metrics, error)
- func (k *KMS) Status(ctx context.Context) (*madmin.KMSStatus, error)
- func (k *KMS) Version(ctx context.Context) (string, error)
- type ListRequest
- type MACRequest
- type Metrics
- type Status
- type StubKMS
- func (s StubKMS) APIs(ctx context.Context) ([]madmin.KMSAPI, error)
- func (s *StubKMS) CreateKey(_ context.Context, req *CreateKeyRequest) error
- func (s StubKMS) Decrypt(_ context.Context, req *DecryptRequest) ([]byte, error)
- func (s StubKMS) GenerateKey(_ context.Context, req *GenerateKeyRequest) (DEK, error)
- func (s StubKMS) ListKeys(ctx context.Context, req *ListRequest) ([]madmin.KMSKeyInfo, string, error)
- func (s StubKMS) MAC(_ context.Context, m *MACRequest) ([]byte, error)
- func (s StubKMS) Status(context.Context) (map[string]madmin.ItemState, error)
- func (s StubKMS) Version(ctx context.Context) (string, error)
- type Type
Constants ¶
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.
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.
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.
const EnvKMSReplicateKeyID = "MINIO_KMS_REPLICATE_KEYID"
EnvKMSReplicateKeyID is an env. variable that controls whether MinIO replicates the KMS key ID. By default, KMS key ID replication is enabled but can be turned off.
Variables ¶
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 exist", } // 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 ¶
IsPresent reports whether a KMS configuration is present. It returns an error if multiple KMS configurations are present or if one configuration is incomplete.
func ReplicateKeyID ¶
func ReplicateKeyID() bool
ReplicateKeyID reports whether KMS key IDs should be included when replicating objects. It's enabled by default. To disable it, set:
MINIO_KMS_REPLICATE_KEYID=off
Some deployments use different KMS clusters with destinct keys on each site. Trying to replicate the KMS key ID can cause requests to fail in such setups.
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 ¶
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 ¶
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 ¶
MarshalText encodes the DEK's key ID and ciphertext as JSON.
func (*DEK) UnmarshalText ¶
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.
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 ¶
NewBuiltin returns a single-key KMS that derives new DEKs from the given key.
func ParseSecretKey ¶
ParseSecretKey parses s as <key-id>:<base64> and returns a KMS that uses s as builtin single key as KMS implementation.
func (*KMS) APIs ¶
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 ¶
Decrypt decrypts a ciphertext using the master key req.Name. It returns ErrKeyNotFound if the key does not exist.
func (*KMS) GenerateKey ¶
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) ListKeys ¶
func (k *KMS) ListKeys(ctx context.Context, req *ListRequest) ([]madmin.KMSKeyInfo, string, error)
ListKeys returns a list of keys with metadata and a potential next name from where to continue a subsequent listing.
func (*KMS) MAC ¶
MAC generates the checksum of the given req.Message using the key with the req.Name at the KMS.
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 StubKMS ¶
type StubKMS struct {
KeyNames []string
}
StubKMS is a KMS implementation for tests
func (*StubKMS) CreateKey ¶
func (s *StubKMS) CreateKey(_ context.Context, req *CreateKeyRequest) error
CreateKey creates a new key with the given name.
func (StubKMS) GenerateKey ¶
GenerateKey is a non-functional stub.
func (StubKMS) ListKeys ¶
func (s StubKMS) ListKeys(ctx context.Context, req *ListRequest) ([]madmin.KMSKeyInfo, string, error)
ListKeys returns a list of keys with metadata.