encryption

README

PVC Encryption Mutator

The PVC Encryption Mutator ensures that PVCs that have requested encryption have a valid configuration, generating encryption keys if needed.

Users may request volume encryption by setting the storageos.com/encrption=true label on the PVC. PVCs that don't have this label will be ignored and left unchanged.

When encryption has been requested, the mutator checks to see whether encryption keys already exist, and if not, generates them. Keys are stored as Kubernetes Secrets.

Encryption key secret

The reference to the secret containing the volume encryption key is set as annotations on the PVC:

• storageos.com/encryption-secret-name: The name of the secret containing the volume encryption key.
• storageos.com/encryption-secret-namespace: The namespace of the secret containing the volume encryption key. This must match the PVC namespace.

If the secret reference annotations are not set by the user, then they will be generated and set by the api-manager.

Auto-generated secrets will be stored in the PVC namespace. The secret name will be a concatenation of key and the PVC name, separated by ..

If the PVC was created with the secret reference annotations already present, they will be used instead. If they point to a secret that does not exist, a new key will be generated and stored there. If the api-manager does not have permission to write the secret, or the namespace does not exist, then PVC creation will fail.

RBAC

In the default configuration, api-manager requires full access to secrets in the namespaces that PVC will be created in. This is enabled by default.

Trigger

Only PVCs that will be provisioned by StorageOS and have the label storageos.com/encryption=true are candidates for mutation.

Garbage collection

Encryption key secrets must be manually deleted after they are no longer required. This may be automated in the future.

Tunables

There are currently no tunable flags for PVC Encryption.

Documentation

Index

• Constants
• Variables
• func GenerateVolumeSecretName() string
• type EncryptionKeySetter
  • func NewKeySetter(k8s client.Client, labels map[string]string) *EncryptionKeySetter
  • func (s *EncryptionKeySetter) MutatePVC(ctx context.Context, pvc *corev1.PersistentVolumeClaim, namespace string) error
  • func (s *EncryptionKeySetter) NamespaceSecretKeyRef(pvcNamespace string) client.ObjectKey
  • func (s *EncryptionKeySetter) VolumeSecretKeyRef(pvc *corev1.PersistentVolumeClaim, pvcNamespace string) client.ObjectKey
  • func (s *EncryptionKeySetter) VolumeSecretLabels(pvcName string) map[string]string
• type KeyManager

Constants

const (
	// SecretNameAnnotationKey is the name of the pvc annotation to store the
	// encryption secret name in.
	SecretNameAnnotationKey = "storageos.com/encryption-secret-name"

	// SecretNamespaceAnnotationKey is the name of the pvc annotation to store
	// the encryption secret namespace in.
	SecretNamespaceAnnotationKey = "storageos.com/encryption-secret-namespace"

	// VolumeSecretNamePrefix will be used to prefix all volume key secrets.
	VolumeSecretNamePrefix = "storageos-volume-key"

	// VolumeSecretPVCNameLabel is used to set the reference to the PVC name on
	// the volume key secret.  The namespace is not needed as it will be the
	// same as the secret.
	VolumeSecretPVCNameLabel = "storageos.com/pvc"

	// NamespaceSecretName is the name of the secret containing the user key in
	// each namespace with encrypted volumes.
	NamespaceSecretName = "storageos-namespace-key"
)

Variables

var (
	// ErrCrossNamespace is returned if a encryption key secret is requested
	// that is not it the PVC namespace.
	ErrCrossNamespace = errors.New("encryption key secret namespace must match pvc namespace")
)

Functions

func GenerateVolumeSecretName

func GenerateVolumeSecretName() string

GenerateVolumeSecretName returns the name of the secret to use for the volume key.

The secret relates to the StorageOS volume (or Kubernetes PV), not the PVC which may be deleted and then the PV reused. Since the volume hasn't been provisioned yet we don't have a reference for it, so generate a unique identifier to use instead.

Types

type EncryptionKeySetter

type EncryptionKeySetter struct {
	client.Client
	// contains filtered or unexported fields
}

EncryptionKeySetter is responsible for generating and setting pvc encryption keys on a pvc.

func NewKeySetter

func NewKeySetter(k8s client.Client, labels map[string]string) *EncryptionKeySetter

NewKeySetter returns a new PVC encryption key mutating admission controller that generates volume encryption keys and sets references to their location as PVC annotations.

func (*EncryptionKeySetter) MutatePVC

func (s *EncryptionKeySetter) MutatePVC(ctx context.Context, pvc *corev1.PersistentVolumeClaim, namespace string) error

MutatePVC mutates a given pvc with annotations containing its encryption key, if the pvc has encryption enabled.

Errors returned here may block creation of the PVC, depending on the FailurePolicy set in the webhook configuration.

func (*EncryptionKeySetter) NamespaceSecretKeyRef

func (s *EncryptionKeySetter) NamespaceSecretKeyRef(pvcNamespace string) client.ObjectKey

NamespaceSecretKeyRef returns the reference of the secret that should be used to store the user encryption key for a namespace.

This key is used to create volume keys.

func (*EncryptionKeySetter) VolumeSecretKeyRef

func (s *EncryptionKeySetter) VolumeSecretKeyRef(pvc *corev1.PersistentVolumeClaim, pvcNamespace string) client.ObjectKey

VolumeSecretKeyRef returns the reference of the secret that should be used to store the encryption keys for a volume provisioned by the PVC.

func (*EncryptionKeySetter) VolumeSecretLabels

func (s *EncryptionKeySetter) VolumeSecretLabels(pvcName string) map[string]string

VolumeSecretLabels returns the labels that should be set on the volume key secret.

type KeyManager

type KeyManager interface {
	Ensure(ctx context.Context, userKeyRef client.ObjectKey, volKeyRef client.ObjectKey, nsSecretLabels map[string]string, volSecretLabels map[string]string) error
}

KeyManager is the encrption key manager, responsible for creating and retrieving secrets that contain the keys required for volume encryption.