Documentation ¶
Index ¶
- Constants
- Variables
- func IsPresent() (bool, error)
- 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) ListKeyNames(ctx context.Context, req *ListRequest) ([]string, 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 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.
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 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 ¶
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) ListKeyNames ¶
ListKeyNames returns a list of key names 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.