crypto

package
v0.0.0-...-1ed3a2a Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2020 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package crypto implements AWS S3 related cryptographic building blocks for implementing Server-Side-Encryption (SSE-S3) and Server-Side-Encryption with customer provided keys (SSE-C).

All objects are encrypted with an unique and randomly generated 'ObjectKey'. The ObjectKey itself is never stored in plaintext. Instead it is only stored in a sealed from. The sealed 'ObjectKey' is created by encrypting the 'ObjectKey' with an unique key-encryption-key. Given the correct key-encryption-key the sealed 'ObjectKey' can be unsealed and the object can be decrypted.

## SSE-C

SSE-C computes the key-encryption-key from the client-provided key, an initialization vector (IV) and the bucket/object path.

  1. Encrypt: Input: ClientKey, bucket, object, metadata, object_data - IV := Random({0,1}²⁵⁶) - ObjectKey := SHA256(ClientKey || Random({0,1}²⁵⁶)) - KeyEncKey := HMAC-SHA256(ClientKey, IV || 'SSE-C' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) - SealedKey := DAREv2_Enc(KeyEncKey, ObjectKey) - enc_object_data := DAREv2_Enc(ObjectKey, object_data) - metadata <- IV - metadata <- SealedKey Output: enc_object_data, metadata
  1. Decrypt: Input: ClientKey, bucket, object, metadata, enc_object_data - IV <- metadata - SealedKey <- metadata - KeyEncKey := HMAC-SHA256(ClientKey, IV || 'SSE-C' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) - ObjectKey := DAREv2_Dec(KeyEncKey, SealedKey) - object_data := DAREv2_Dec(ObjectKey, enc_object_data) Output: object_data

## SSE-S3

SSE-S3 can use either a master key or a KMS as root-of-trust. The en/decryption slightly depens upon which root-of-trust is used.

### SSE-S3 and single master key

The master key is used to derive unique object- and key-encryption-keys. SSE-S3 with a single master key works as SSE-C where the master key is used as the client-provided key.

  1. Encrypt: Input: MasterKey, bucket, object, metadata, object_data - IV := Random({0,1}²⁵⁶) - ObjectKey := SHA256(MasterKey || Random({0,1}²⁵⁶)) - KeyEncKey := HMAC-SHA256(MasterKey, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) - SealedKey := DAREv2_Enc(KeyEncKey, ObjectKey) - enc_object_data := DAREv2_Enc(ObjectKey, object_data) - metadata <- IV - metadata <- SealedKey Output: enc_object_data, metadata
  1. Decrypt: Input: MasterKey, bucket, object, metadata, enc_object_data - IV <- metadata - SealedKey <- metadata - KeyEncKey := HMAC-SHA256(MasterKey, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) - ObjectKey := DAREv2_Dec(KeyEncKey, SealedKey) - object_data := DAREv2_Dec(ObjectKey, enc_object_data) Output: object_data

### SSE-S3 and KMS

SSE-S3 requires that the KMS provides two functions:

  1. Generate(KeyID) -> (Key, EncKey)
  2. Unseal(KeyID, EncKey) -> Key
  1. Encrypt: Input: KeyID, bucket, object, metadata, object_data - Key, EncKey := Generate(KeyID) - IV := Random({0,1}²⁵⁶) - ObjectKey := SHA256(Key, Random({0,1}²⁵⁶)) - KeyEncKey := HMAC-SHA256(Key, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) - SealedKey := DAREv2_Enc(KeyEncKey, ObjectKey) - enc_object_data := DAREv2_Enc(ObjectKey, object_data) - metadata <- IV - metadata <- KeyID - metadata <- EncKey - metadata <- SealedKey Output: enc_object_data, metadata
  1. Decrypt: Input: bucket, object, metadata, enc_object_data - KeyID <- metadata - EncKey <- metadata - IV <- metadata - SealedKey <- metadata - Key := Unseal(KeyID, EncKey) - KeyEncKey := HMAC-SHA256(Key, IV || 'SSE-S3' || 'DAREv2-HMAC-SHA256' || bucket || '/' || object) - ObjectKey := DAREv2_Dec(KeyEncKey, SealedKey) - object_data := DAREv2_Dec(ObjectKey, enc_object_data) Output: object_data

Index

Constants

View Source 
const (
	KMSVaultEndpoint      = "endpoint"
	KMSVaultCAPath        = "capath"
	KMSVaultKeyName       = "key_name"
	KMSVaultKeyVersion    = "key_version"
	KMSVaultNamespace     = "namespace"
	KMSVaultAuthType      = "auth_type"
	KMSVaultAppRoleID     = "auth_approle_id"
	KMSVaultAppRoleSecret = "auth_approle_secret"
)

KMS Vault constants.

View Source 
const (
	KMSKesEndpoint = "endpoint"
	KMSKesKeyFile  = "key_file"
	KMSKesCertFile = "cert_file"
	KMSKesCAPath   = "capath"
	KMSKesKeyName  = "key_name"
)

KMS kes constants.

View Source 
const (
	// EnvKMSMasterKey is the environment variable used to specify
	// a KMS master key used to protect SSE-S3 per-object keys.
	// Valid values must be of the from: "KEY_ID:32_BYTE_HEX_VALUE".
	EnvKMSMasterKey = "MINIO_KMS_MASTER_KEY"

	// EnvKMSAutoEncryption is the environment variable used to en/disable
	// SSE-S3 auto-encryption. SSE-S3 auto-encryption, if enabled,
	// requires a valid KMS configuration and turns any non-SSE-C
	// request into an SSE-S3 request.
	// If present EnvAutoEncryption must be either "on" or "off".
	EnvKMSAutoEncryption = "MINIO_KMS_AUTO_ENCRYPTION"
)
View Source 
const (
	// EnvKMSVaultEndpoint is the environment variable used to specify
	// the vault HTTPS endpoint.
	EnvKMSVaultEndpoint = "MINIO_KMS_VAULT_ENDPOINT"

	// EnvKMSVaultAuthType is the environment variable used to specify
	// the authentication type for vault.
	EnvKMSVaultAuthType = "MINIO_KMS_VAULT_AUTH_TYPE"

	// EnvKMSVaultAppRoleID is the environment variable used to specify
	// the vault AppRole ID.
	EnvKMSVaultAppRoleID = "MINIO_KMS_VAULT_APPROLE_ID"

	// EnvKMSVaultAppSecretID is the environment variable used to specify
	// the vault AppRole secret corresponding to the AppRole ID.
	EnvKMSVaultAppSecretID = "MINIO_KMS_VAULT_APPROLE_SECRET"

	// EnvKMSVaultKeyVersion is the environment variable used to specify
	// the vault key version.
	EnvKMSVaultKeyVersion = "MINIO_KMS_VAULT_KEY_VERSION"

	// EnvKMSVaultKeyName is the environment variable used to specify
	// the vault named key-ring. In the S3 context it's referred as
	// customer master key ID (CMK-ID).
	EnvKMSVaultKeyName = "MINIO_KMS_VAULT_KEY_NAME"

	// EnvKMSVaultCAPath is the environment variable used to specify the
	// path to a directory of PEM-encoded CA cert files. These CA cert
	// files are used to authenticate MinIO to Vault over mTLS.
	EnvKMSVaultCAPath = "MINIO_KMS_VAULT_CAPATH"

	// EnvKMSVaultNamespace is the environment variable used to specify
	// vault namespace. The vault namespace is used if the enterprise
	// version of Hashicorp Vault is used.
	EnvKMSVaultNamespace = "MINIO_KMS_VAULT_NAMESPACE"
)
View Source 
const (
	// EnvKMSKesEndpoint is the environment variable used to specify
	// one or multiple KES server HTTPS endpoints. The individual
	// endpoints should be separated by ','.
	EnvKMSKesEndpoint = "MINIO_KMS_KES_ENDPOINT"

	// EnvKMSKesKeyFile is the environment variable used to specify
	// the TLS private key used by MinIO to authenticate to the kes
	// server HTTPS via mTLS.
	EnvKMSKesKeyFile = "MINIO_KMS_KES_KEY_FILE"

	// EnvKMSKesCertFile is the environment variable used to specify
	// the TLS certificate used by MinIO to authenticate to the kes
	// server HTTPS via mTLS.
	EnvKMSKesCertFile = "MINIO_KMS_KES_CERT_FILE"

	// EnvKMSKesCAPath is the environment variable used to specify
	// the TLS root certificates used by MinIO to verify the certificate
	// presented by to the kes server when establishing a TLS connection.
	EnvKMSKesCAPath = "MINIO_KMS_KES_CA_PATH"

	// EnvKMSKesKeyName is the environment variable used to specify
	// the (default) key at the kes server. In the S3 context it's
	// referred as customer master key ID (CMK-ID).
	EnvKMSKesKeyName = "MINIO_KMS_KES_KEY_NAME"
)
View Source 
const (
	// SSEKmsID is the HTTP header key referencing the SSE-KMS
	// key ID.
	SSEKmsID = SSEHeader + "-Aws-Kms-Key-Id"

	// SSEKmsContext is the HTTP header key referencing the
	// SSE-KMS encryption context.
	SSEKmsContext = SSEHeader + "-Context"
)
View Source 
const (
	// SSECAlgorithm is the HTTP header key referencing
	// the SSE-C algorithm.
	SSECAlgorithm = SSEHeader + "-Customer-Algorithm"

	// SSECKey is the HTTP header key referencing the
	// SSE-C client-provided key..
	SSECKey = SSEHeader + "-Customer-Key"

	// SSECKeyMD5 is the HTTP header key referencing
	// the MD5 sum of the client-provided key.
	SSECKeyMD5 = SSEHeader + "-Customer-Key-Md5"
)
View Source 
const (
	// SSECopyAlgorithm is the HTTP header key referencing
	// the SSE-C algorithm for SSE-C copy requests.
	SSECopyAlgorithm = "X-Amz-Copy-Source-Server-Side-Encryption-Customer-Algorithm"

	// SSECopyKey is the HTTP header key referencing the SSE-C
	// client-provided key for SSE-C copy requests.
	SSECopyKey = "X-Amz-Copy-Source-Server-Side-Encryption-Customer-Key"

	// SSECopyKeyMD5 is the HTTP header key referencing the
	// MD5 sum of the client key for SSE-C copy requests.
	SSECopyKeyMD5 = "X-Amz-Copy-Source-Server-Side-Encryption-Customer-Key-Md5"
)
View Source 
const (
	// SSEAlgorithmAES256 is the only supported value for the SSE-S3 or SSE-C algorithm header.
	// For SSE-S3 see: https://docs.aws.amazon.com/AmazonS3/latest/dev/SSEUsingRESTAPI.html
	// For SSE-C  see: https://docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html
	SSEAlgorithmAES256 = "AES256"

	// SSEAlgorithmKMS is the value of 'X-Amz-Server-Side-Encryption' for SSE-KMS.
	// See: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingKMSEncryption.html
	SSEAlgorithmKMS = "aws:kms"
)
View Source 
const (
	// EnvKMSMasterKeyLegacy is the environment variable used to specify
	// a KMS master key used to protect SSE-S3 per-object keys.
	// Valid values must be of the from: "KEY_ID:32_BYTE_HEX_VALUE".
	EnvKMSMasterKeyLegacy = "MINIO_SSE_MASTER_KEY"

	// EnvAutoEncryptionLegacy is the environment variable used to en/disable
	// SSE-S3 auto-encryption. SSE-S3 auto-encryption, if enabled,
	// requires a valid KMS configuration and turns any non-SSE-C
	// request into an SSE-S3 request.
	// If present EnvAutoEncryption must be either "on" or "off".
	EnvAutoEncryptionLegacy = "MINIO_SSE_AUTO_ENCRYPTION"
)
View Source 
const (
	// EnvLegacyVaultEndpoint is the environment variable used to specify
	// the vault HTTPS endpoint.
	EnvLegacyVaultEndpoint = "MINIO_SSE_VAULT_ENDPOINT"

	// EnvLegacyVaultAuthType is the environment variable used to specify
	// the authentication type for vault.
	EnvLegacyVaultAuthType = "MINIO_SSE_VAULT_AUTH_TYPE"

	// EnvLegacyVaultAppRoleID is the environment variable used to specify
	// the vault AppRole ID.
	EnvLegacyVaultAppRoleID = "MINIO_SSE_VAULT_APPROLE_ID"

	// EnvLegacyVaultAppSecretID is the environment variable used to specify
	// the vault AppRole secret corresponding to the AppRole ID.
	EnvLegacyVaultAppSecretID = "MINIO_SSE_VAULT_APPROLE_SECRET"

	// EnvLegacyVaultKeyVersion is the environment variable used to specify
	// the vault key version.
	EnvLegacyVaultKeyVersion = "MINIO_SSE_VAULT_KEY_VERSION"

	// EnvLegacyVaultKeyName is the environment variable used to specify
	// the vault named key-ring. In the S3 context it's referred as
	// customer master key ID (CMK-ID).
	EnvLegacyVaultKeyName = "MINIO_SSE_VAULT_KEY_NAME"

	// EnvLegacyVaultCAPath is the environment variable used to specify the
	// path to a directory of PEM-encoded CA cert files. These CA cert
	// files are used to authenticate MinIO to Vault over mTLS.
	EnvLegacyVaultCAPath = "MINIO_SSE_VAULT_CAPATH"

	// EnvLegacyVaultNamespace is the environment variable used to specify
	// vault namespace. The vault namespace is used if the enterprise
	// version of Hashicorp Vault is used.
	EnvLegacyVaultNamespace = "MINIO_SSE_VAULT_NAMESPACE"
)
View Source 
const (
	// SSEMultipart is the metadata key indicating that the object
	// was uploaded using the S3 multipart API and stored using
	// some from of server-side-encryption.
	SSEMultipart = "X-Minio-Internal-Encrypted-Multipart"

	// SSEIV is the metadata key referencing the random initialization
	// vector (IV) used for SSE-S3 and SSE-C key derivation.
	SSEIV = "X-Minio-Internal-Server-Side-Encryption-Iv"

	// SSESealAlgorithm is the metadata key referencing the algorithm
	// used by SSE-C and SSE-S3 to encrypt the object.
	SSESealAlgorithm = "X-Minio-Internal-Server-Side-Encryption-Seal-Algorithm"

	// SSECSealedKey is the metadata key referencing the sealed object-key for SSE-C.
	SSECSealedKey = "X-Minio-Internal-Server-Side-Encryption-Sealed-Key"

	// S3SealedKey is the metadata key referencing the sealed object-key for SSE-S3.
	S3SealedKey = "X-Minio-Internal-Server-Side-Encryption-S3-Sealed-Key"

	// S3KMSKeyID is the metadata key referencing the KMS key-id used to
	// generate/decrypt the S3-KMS-Sealed-Key. It is only used for SSE-S3 + KMS.
	S3KMSKeyID = "X-Minio-Internal-Server-Side-Encryption-S3-Kms-Key-Id"

	// S3KMSSealedKey is the metadata key referencing the encrypted key generated
	// by KMS. It is only used for SSE-S3 + KMS.
	S3KMSSealedKey = "X-Minio-Internal-Server-Side-Encryption-S3-Kms-Sealed-Key"
)
View Source 
const (
	// SealAlgorithm is the encryption/sealing algorithm used to derive & seal
	// the key-encryption-key and to en/decrypt the object data.
	SealAlgorithm = "DAREv2-HMAC-SHA256"

	// InsecureSealAlgorithm is the legacy encryption/sealing algorithm used
	// to derive & seal the key-encryption-key and to en/decrypt the object data.
	// This algorithm should not be used for new objects because its key derivation
	// is not optimal. See: https://github.com/cdbarbosa/clone/pull/6121
	InsecureSealAlgorithm = "DARE-SHA256"
)
View Source 
const SSEHeader = "X-Amz-Server-Side-Encryption"

SSEHeader is the general AWS SSE HTTP header key.

Variables

View Source 
var (
	DefaultVaultKVS = config.KVS{
		config.KV{
			Key:   KMSVaultEndpoint,
			Value: "",
		},
		config.KV{
			Key:   KMSVaultKeyName,
			Value: "",
		},
		config.KV{
			Key:   KMSVaultAuthType,
			Value: "approle",
		},
		config.KV{
			Key:   KMSVaultAppRoleID,
			Value: "",
		},
		config.KV{
			Key:   KMSVaultAppRoleSecret,
			Value: "",
		},
		config.KV{
			Key:   KMSVaultCAPath,
			Value: "",
		},
		config.KV{
			Key:   KMSVaultKeyVersion,
			Value: "",
		},
		config.KV{
			Key:   KMSVaultNamespace,
			Value: "",
		},
	}

	DefaultKesKVS = config.KVS{
		config.KV{
			Key:   KMSKesEndpoint,
			Value: "",
		},
		config.KV{
			Key:   KMSKesKeyName,
			Value: "",
		},
		config.KV{
			Key:   KMSKesCertFile,
			Value: "",
		},
		config.KV{
			Key:   KMSKesKeyFile,
			Value: "",
		},
		config.KV{
			Key:   KMSKesCAPath,
			Value: "",
		},
	}
)

DefaultKVS - default KV crypto config

View Source 
var (
	// ErrInvalidEncryptionMethod indicates that the specified SSE encryption method
	// is not supported.
	ErrInvalidEncryptionMethod = Errorf("The encryption method is not supported")

	// ErrInvalidCustomerAlgorithm indicates that the specified SSE-C algorithm
	// is not supported.
	ErrInvalidCustomerAlgorithm = Errorf("The SSE-C algorithm is not supported")

	// ErrMissingCustomerKey indicates that the HTTP headers contains no SSE-C client key.
	ErrMissingCustomerKey = Errorf("The SSE-C request is missing the customer key")

	// ErrMissingCustomerKeyMD5 indicates that the HTTP headers contains no SSE-C client key
	// MD5 checksum.
	ErrMissingCustomerKeyMD5 = Errorf("The SSE-C request is missing the customer key MD5")

	// ErrInvalidCustomerKey indicates that the SSE-C client key is not valid - e.g. not a
	// base64-encoded string or not 256 bits long.
	ErrInvalidCustomerKey = Errorf("The SSE-C client key is invalid")

	// ErrSecretKeyMismatch indicates that the provided secret key (SSE-C client key / SSE-S3 KMS key)
	// does not match the secret key used during encrypting the object.
	ErrSecretKeyMismatch = Errorf("The secret key does not match the secret key used during upload")

	// ErrCustomerKeyMD5Mismatch indicates that the SSE-C key MD5 does not match the
	// computed MD5 sum. This means that the client provided either the wrong key for
	// a certain MD5 checksum or the wrong MD5 for a certain key.
	ErrCustomerKeyMD5Mismatch = Errorf("The provided SSE-C key MD5 does not match the computed MD5 of the SSE-C key")
	// ErrIncompatibleEncryptionMethod indicates that both SSE-C headers and SSE-S3 headers were specified, and are incompatible
	// The client needs to remove the SSE-S3 header or the SSE-C headers
	ErrIncompatibleEncryptionMethod = Errorf("Server side encryption specified with both SSE-C and SSE-S3 headers")
)
View Source 
var (
	// SSEC represents AWS SSE-C. It provides functionality to handle
	// SSE-C requests.
	SSEC = ssec{}

	// SSECopy represents AWS SSE-C for copy requests. It provides
	// functionality to handle SSE-C copy requests.
	SSECopy = ssecCopy{}
)
View Source 
var (
	HelpVault = config.HelpKVS{
		config.HelpKV{
			Key:         KMSVaultEndpoint,
			Description: `API endpoint e.g. "http://vault-endpoint-ip:8200"`,
			Type:        "url",
		},
		config.HelpKV{
			Key:         KMSVaultKeyName,
			Description: `unique transit key name - e.g. "my-minio-key"`,
			Type:        "string",
		},
		config.HelpKV{
			Key:         KMSVaultAuthType,
			Description: `supported auth type(s) ["approle"], defaults to "approle"`,
			Type:        "string",
		},
		config.HelpKV{
			Key:         KMSVaultAppRoleID,
			Description: `unique role ID for approle`,
			Type:        "string",
		},
		config.HelpKV{
			Key:         KMSVaultAppRoleSecret,
			Description: `unique secret ID for approle`,
			Type:        "string",
		},
		config.HelpKV{
			Key:         KMSVaultNamespace,
			Description: `optional KMS namespace e.g. "customer1"`,
			Optional:    true,
			Type:        "string",
		},
		config.HelpKV{
			Key:         KMSVaultKeyVersion,
			Description: `optional key version number`,
			Optional:    true,
			Type:        "number",
		},
		config.HelpKV{
			Key:         KMSVaultCAPath,
			Description: `optional path to PEM-encoded CA certs e.g. "/home/user/custom-certs"`,
			Optional:    true,
			Type:        "path",
		},
		config.HelpKV{
			Key:         config.Comment,
			Description: config.DefaultComment,
			Optional:    true,
			Type:        "sentence",
		},
	}

	HelpKes = config.HelpKVS{
		config.HelpKV{
			Key:         KMSKesEndpoint,
			Description: `API endpoint - e.g. "https://kes-endpoint:7373"`,
			Type:        "url",
		},
		config.HelpKV{
			Key:         KMSKesKeyName,
			Description: `unique key name - e.g. "my-minio-key"`,
			Type:        "string",
		},
		config.HelpKV{
			Key:         KMSKesCertFile,
			Description: `path to client certificate for TLS auth - e.g. /etc/keys/public.crt`,
			Type:        "path",
		},
		config.HelpKV{
			Key:         KMSKesKeyFile,
			Description: `path to client private key for TLS auth - e.g. /etc/keys/private.key`,
			Type:        "path",
		},
		config.HelpKV{
			Key:         KMSKesCAPath,
			Description: `path to PEM-encoded cert(s) to verify kes server cert - e.g. /etc/keys/CAs`,
			Optional:    true,
			Type:        "path",
		},
		config.HelpKV{
			Key:         config.Comment,
			Description: config.DefaultComment,
			Optional:    true,
			Type:        "sentence",
		},
	}
)

Help template for KMS vault

View Source 
var ErrKESKeyExists = NewKESError(http.StatusBadRequest, "key does already exist")

ErrKESKeyExists is the error returned a KES server when a master key does exist.

View Source 
var (
	//ErrKMSAuthLogin is raised when there is a failure authenticating to KMS
	ErrKMSAuthLogin = Errorf("Vault service did not return auth info")
)
View Source 
var S3 = s3{}

S3 represents AWS SSE-S3. It provides functionality to handle SSE-S3 requests.

View Source 
var S3KMS = s3KMS{}

S3KMS represents AWS SSE-KMS. It provides functionality to handle SSE-KMS requests.

Functions

func CreateMultipartMetadata 

func CreateMultipartMetadata(metadata map[string]string) map[string]string

CreateMultipartMetadata adds the multipart flag entry to metadata and returns modifed metadata. It allocates a new metadata map if metadata is nil.

func DecryptSinglePart 

func DecryptSinglePart(w io.Writer, offset, length int64, key ObjectKey) io.WriteCloser

DecryptSinglePart decrypts an io.Writer which must an object uploaded with the single-part PUT API. The offset and length specify the requested range.

func EnabledKes 

func EnabledKes(kvs config.KVS) bool

EnabledKes returns true if kes as KMS is enabled.

func EnabledVault 

func EnabledVault(kvs config.KVS) bool

EnabledVault returns true if HashiCorp Vault is enabled.

func EncryptMultiPart 

func EncryptMultiPart(r io.Reader, partID int, key ObjectKey) io.Reader

EncryptMultiPart encrypts an io.Reader which must be the body of multi-part PUT request. It derives an unique encryption key from the partID and the object key.

func EncryptSinglePart 

func EncryptSinglePart(r io.Reader, key ObjectKey) io.Reader

EncryptSinglePart encrypts an io.Reader which must be the the body of a single-part PUT request.

func Errorf 

func Errorf(format string, a ...interface{}) error

Errorf - formats according to a format specifier and returns the string as a value that satisfies error of type crypto.Error

func GenerateIV 

func GenerateIV(random io.Reader) (iv [32]byte)

GenerateIV generates a new random 256 bit IV from the provided source of randomness. If random is nil the default PRNG of the system (crypto/rand) is used.

func IsETagSealed 

func IsETagSealed(etag []byte) bool

IsETagSealed returns true if the etag seems to be encrypted.

func IsEncrypted 

func IsEncrypted(metadata map[string]string) bool

IsEncrypted returns true if the object metadata indicates that it was uploaded using some form of server-side-encryption.

IsEncrypted only checks whether the metadata contains at least one entry indicating SSE-C or SSE-S3.

func IsMultiPart 

func IsMultiPart(metadata map[string]string) bool

IsMultiPart returns true if the object metadata indicates that it was uploaded using some form of server-side-encryption and the S3 multipart API.

func IsRequested 

func IsRequested(h http.Header) bool

IsRequested returns true if the HTTP headers indicates that any form server-side encryption (SSE-C, SSE-S3 or SSE-KMS) is requested.

func IsSourceEncrypted 

func IsSourceEncrypted(metadata map[string]string) bool

IsSourceEncrypted returns true if the source is encrypted

func LinearJitterBackoff 

func LinearJitterBackoff(min, max time.Duration, attemptNum int) time.Duration

LinearJitterBackoff provides the time.Duration for a caller to perform linear backoff based on the attempt number and with jitter to prevent a thundering herd.

min and max here are *not* absolute values. The number to be multiplied by the attempt number will be chosen at random from between them, thus they are bounding the jitter.

For instance: * To get strictly linear backoff of one second increasing each retry, set both to one second (1s, 2s, 3s, 4s, ...) * To get a small amount of jitter centered around one second increasing each retry, set to around one second, such as a min of 800ms and max of 1200ms (892ms, 2102ms, 2945ms, 4312ms, ...) * To get extreme jitter, set to a very wide spread, such as a min of 100ms and a max of 20s (15382ms, 292ms, 51321ms, 35234ms, ...)

func NewKESError 

func NewKESError(code int, text string) error

NewKESError returns a new KES API error with the given HTTP status code and error message.

Two errors with the same status code and error message are equal: 

e1 == e2 // true.

func RemoveInternalEntries 

func RemoveInternalEntries(metadata map[string]string)

RemoveInternalEntries removes all crypto-specific internal metadata entries from the metadata map.

func RemoveSSEHeaders 

func RemoveSSEHeaders(metadata map[string]string)

RemoveSSEHeaders removes all crypto-specific SSE header entries from the metadata map.

func RemoveSensitiveEntries 

func RemoveSensitiveEntries(metadata map[string]string)

RemoveSensitiveEntries removes confidential encryption information - e.g. the SSE-C key - from the metadata map. It has the same semantics as RemoveSensitiveHeaders.

func RemoveSensitiveHeaders 

func RemoveSensitiveHeaders(h http.Header)

RemoveSensitiveHeaders removes confidential encryption information - e.g. the SSE-C key - from the HTTP headers. It has the same semantics as RemoveSensitiveEntires.

func SetKMSConfig 

func SetKMSConfig(s config.Config, cfg KMSConfig)

SetKMSConfig helper to migrate from older KMSConfig to new KV.

Types

type Context 

type Context map[string]string

Context is a list of key-value pairs cryptographically associated with a certain object.

func (Context) AppendTo 

func (c Context) AppendTo(dst []byte) (output []byte)

AppendTo appends the context in a canonical from to dst.

AppendTo sorts the context keys and writes the sorted key-value pairs as canonical JSON object to w.

Note that neither keys nor values are escaped for JSON.

func (Context) WriteTo 

func (c Context) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes the context in a canonical from to w. It returns the number of bytes and the first error encounter during writing to w, if any.

WriteTo sorts the context keys and writes the sorted key-value pairs as canonical JSON object to w.

Note that neither keys nor values are escaped for JSON.

type Error 

type Error struct {
	// contains filtered or unexported fields
}

Error is the generic type for any error happening during decrypting an object. It indicates that the object itself or its metadata was modified accidentally or maliciously.

func (Error) Error 

func (e Error) Error() string

Error 'error' compatible method.

func (Error) Unwrap 

func (e Error) Unwrap() error

Unwrap the internal error.

type KMS 

type KMS interface {
	// DefaultKeyID returns the default master key ID. It should be
	// used for SSE-S3 and whenever a S3 client requests SSE-KMS but
	// does not specify an explicit SSE-KMS key ID.
	DefaultKeyID() string

	// CreateKey creates a new master key with the given key ID
	// at the KMS.
	CreateKey(keyID string) error

	// GenerateKey generates a new random data key using
	// the master key referenced by the keyID. It returns
	// the plaintext key and the sealed plaintext key
	// on success.
	//
	// The context is cryptographically bound to the
	// generated key. The same context must be provided
	// again to unseal the generated key.
	GenerateKey(keyID string, context Context) (key [32]byte, sealedKey []byte, err error)

	// UnsealKey unseals the sealedKey using the master key
	// referenced by the keyID. The provided context must
	// match the context used to generate the sealed key.
	UnsealKey(keyID string, sealedKey []byte, context Context) (key [32]byte, err error)

	// Info returns descriptive information about the KMS,
	// like the default key ID and authentication method.
	Info() KMSInfo
}

KMS represents an active and authenticted connection to a Key-Management-Service. It supports generating data key generation and unsealing of KMS-generated data keys.

func NewKMS 

func NewKMS(cfg KMSConfig) (kms KMS, err error)

NewKMS - initialize a new KMS.

func NewKes 

func NewKes(cfg KesConfig) (KMS, error)

NewKes returns a new kes KMS client. The returned KMS uses the X.509 certificate to authenticate itself to the kes server available at address.

The defaultKeyID is the key ID returned when calling KMS.KeyID().

func NewMasterKey 

func NewMasterKey(keyID string, key [32]byte) KMS

NewMasterKey returns a basic KMS implementation from a single 256 bit master key.

The KMS accepts any keyID but binds the keyID and context cryptographically to the generated keys.

func NewVault 

func NewVault(config VaultConfig) (KMS, error)

NewVault initializes Hashicorp Vault KMS by authenticating to Vault with the credentials in config and gets a client token for future api calls.

func ParseMasterKey 

func ParseMasterKey(envArg string) (KMS, error)

ParseMasterKey parses the value of the environment variable `EnvKMSMasterKey` and returns a key-ID and a master-key KMS on success.

type KMSConfig 

type KMSConfig struct {
	AutoEncryption bool        `json:"-"`
	Vault          VaultConfig `json:"vault"`
	Kes            KesConfig   `json:"kes"`
}

KMSConfig has the KMS config for hashicorp vault

func LookupConfig 

func LookupConfig(c config.Config, defaultRootCAsDir string, transport *http.Transport) (KMSConfig, error)

LookupConfig lookup vault or kes config, returns KMSConfig to configure KMS object for object encryption

type KMSInfo 

type KMSInfo struct {
	Endpoints []string
	Name      string
	AuthType  string
}

KMSInfo contains some describing information about the KMS.

type KesConfig 

type KesConfig struct {
	Enabled bool

	// The KES server endpoints.
	Endpoint []string

	// The path to the TLS private key used
	// by MinIO to authenticate to the kes
	// server during the TLS handshake (mTLS).
	KeyFile string

	// The path to the TLS certificate used
	// by MinIO to authenticate to the kes
	// server during the TLS handshake (mTLS).
	//
	// The kes server will also allow or deny
	// access based on this certificate.
	// In particular, the kes server will
	// lookup the policy that corresponds to
	// the identity in this certificate.
	CertFile string

	// Path to a file or directory containing
	// the CA certificate(s) that issued / will
	// issue certificates for the kes server.
	//
	// This is required if the TLS certificate
	// of the kes server has not been issued
	// (e.g. b/c it's self-signed) by a CA that
	// MinIO trusts.
	CAPath string

	// The default key ID returned by KMS.KeyID().
	DefaultKeyID string

	// The HTTP transport configuration for
	// the KES client.
	Transport *http.Transport
}

KesConfig contains the configuration required to initialize and connect to a kes server.

func LookupKesConfig 

func LookupKesConfig(kvs config.KVS) (KesConfig, error)

LookupKesConfig lookup kes server configuration.

func (KesConfig) Verify 

func (k KesConfig) Verify() (err error)

Verify verifies if the kes configuration is correct

type ObjectKey 

type ObjectKey [32]byte

ObjectKey is a 256 bit secret key used to encrypt the object. It must never be stored in plaintext.

func GenerateKey 

func GenerateKey(extKey [32]byte, random io.Reader) (key ObjectKey)

GenerateKey generates a unique ObjectKey from a 256 bit external key and a source of randomness. If random is nil the default PRNG of the system (crypto/rand) is used.

func (ObjectKey) DerivePartKey 

func (key ObjectKey) DerivePartKey(id uint32) (partKey [32]byte)

DerivePartKey derives an unique 256 bit key from an ObjectKey and the part index.

func (ObjectKey) Seal 

func (key ObjectKey) Seal(extKey, iv [32]byte, domain, bucket, object string) SealedKey

Seal encrypts the ObjectKey using the 256 bit external key and IV. The sealed key is also cryptographically bound to the object's path (bucket/object) and the domain (SSE-C or SSE-S3).

func (ObjectKey) SealETag 

func (key ObjectKey) SealETag(etag []byte) []byte

SealETag seals the etag using the object key. It does not encrypt empty ETags because such ETags indicate that the S3 client hasn't sent an ETag = MD5(object) and the backend can pick an ETag value.

func (*ObjectKey) Unseal 

func (key *ObjectKey) Unseal(extKey [32]byte, sealedKey SealedKey, domain, bucket, object string) error

Unseal decrypts a sealed key using the 256 bit external key. Since the sealed key may be cryptographically bound to the object's path the same bucket/object as during sealing must be provided. On success the ObjectKey contains the decrypted sealed key.

func (ObjectKey) UnsealETag 

func (key ObjectKey) UnsealETag(etag []byte) ([]byte, error)

UnsealETag unseals the etag using the provided object key. It does not try to decrypt the ETag if len(etag) == 16 because such ETags indicate that the S3 client hasn't sent an ETag = MD5(object) and the backend has picked an ETag value.

type SealedKey 

type SealedKey struct {
	Key       [64]byte // The encrypted and authenticted object-key.
	IV        [32]byte // The random IV used to encrypt the object-key.
	Algorithm string   // The sealing algorithm used to encrypt the object key.
}

SealedKey represents a sealed object key. It can be stored at an untrusted location.

type VaultAppRole 

type VaultAppRole struct {
	ID     string `json:"id"`     // The AppRole access ID
	Secret string `json:"secret"` // The AppRole secret
}

VaultAppRole represents vault AppRole authentication credentials

type VaultAuth 

type VaultAuth struct {
	Type    string       `json:"type"`    // The authentication type
	AppRole VaultAppRole `json:"approle"` // The AppRole authentication credentials
}

VaultAuth represents vault authentication type. Currently the only supported authentication type is AppRole.

type VaultConfig 

type VaultConfig struct {
	Enabled   bool      `json:"-"`
	Endpoint  string    `json:"endpoint"` // The vault API endpoint as URL
	CAPath    string    `json:"-"`        // The path to PEM-encoded certificate files used for mTLS. Currently not used in config file.
	Auth      VaultAuth `json:"auth"`     // The vault authentication configuration
	Key       VaultKey  `json:"key-id"`   // The named key used for key-generation / decryption.
	Namespace string    `json:"-"`        // The vault namespace of enterprise vault instances
}

VaultConfig represents vault configuration.

func LookupVaultConfig 

func LookupVaultConfig(kvs config.KVS) (VaultConfig, error)

LookupVaultConfig extracts the KMS configuration provided by environment variables and merge them with the provided KMS configuration. The merging follows the following rules:

1. A valid value provided as environment variable is higher prioritized than the provided configuration and overwrites the value from the configuration file.

2. A value specified as environment variable never changes the configuration file. So it is never made a persistent setting.

It sets the global KMS configuration according to the merged configuration on succes.

func (*VaultConfig) Verify 

func (v *VaultConfig) Verify() (err error)

Verify returns a nil error if the vault configuration is valid. A valid configuration is either empty or contains valid non-default values.

type VaultKey 

type VaultKey struct {
	Name    string `json:"name"`    // The name of the encryption key-ring
	Version int    `json:"version"` // The key version
}

VaultKey represents vault encryption key-ring.

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.