Understanding encryption for Portworx

Encryption overview

The following image illustrates the encryption workflow in Portworx when you set up per-volume encryption.

The user creates a PVC with a Portworx storage class and requests the storage to be encrypted.
Portworx invokes the IBM Key Protect or Hyper Protect Crypto Services API WrapCreateDEK to create a passphrase by using the customer root key (CRK) that is stored in the Portworx secret.
The IBM Key Protect or Hyper Protect Crypto Services service instance generates a 256-bit passphrase and wraps the passphrase in the DEK. The DEK is returned to the Portworx cluster.
The Portworx cluster uses the passphrase to encrypt the volume.
The Portworx cluster stores the DEK in plain text in the Portworx etcd database, associates the volume ID with the DEK, and removes the passphrase from its memory.

Decryption overview

The following image illustrates the decryption workflow in Portworx when you set up per-volume encryption.

Kubernetes sends a request to decrypt an encrypted volume.
Portworx requests the DEK for the volume from the Portworx etcd database.
The Portworx etcd looks up the DEK and returns the DEK to the Portworx cluster.
The Portworx cluster calls the IBM Key Protect or Hyper Protect Crypto Services API UnWrapDEK by providing the DEK and the root key (CRK) that is stored in the Portworx secret.
IBM Key Protect or Hyper Protect Crypto Services unwraps the DEK to extract the passphrase and returns the passphrase to the Portworx cluster.
The Portworx cluster uses the passphrase to decrypt the volume. After the volume is decrypted, the passphrase is removed from the Portworx cluster.

Setting up volume encryption

To protect your data in a Portworx volume, you can create an instance of a KMS provider such as IBM Key Protect or Hyper Protect Crypto Services.

If you don't want to use IBM Key Protect or Hyper Protect Crypto Services root keys to encrypt your volumes, you can select Kubernetes Secret as your Portworx secret store type during the Portworx installation. This setting gives you the option to store your own custom encryption key in a Kubernetes secret after you install Portworx. For more information, see the Portworx documentation.

Getting your KMS instance and credentials

Setting up volume encryption with Hyper Protect Crypto Services

Create a service instance.
Create a root key.
Create a service ID.
Private clusters: Create a virtual private endpoint gateway that allows access to your KMS instance. Make sure to bind at least 1 IP address from each subnet in your VPC to the VPE.
Retrieve the Key Management public endpoint URL. Make sure that you note your endpoint in the correct format; for example, https://api.us-south.hs-crypto.cloud.ibm.com:<port>. For more information, see the Hyper Protect Crypto Services API documentation.

Setting up volume encryption with IBM Key Protect

Create a service instance.
Create a root key.
Create a service ID.
Retrieve the region where you created your service instance and make a note. You need this value later when you create your secret.
Private clusters: Create a virtual private endpoint gateway that allows access to your KMS instance. Make sure to bind at least 1 IP address from each subnet in your VPC to the VPE.

Creating a secret in your cluster

Encode the credentials that you retrieved in the previous section to base64 and note all the base64 encoded values. Repeat this command for each parameter to retrieve the base64 encoded value.
```
echo -n "<value>" | base64
```
Create a project in your cluster called portworx.
```
oc create ns portworx
```
Create a Kubernetes secret named px-ibm in the portworx project of your cluster to store your IBM Key Protect information.
1. Create a configuration file for your Kubernetes secret with the following content.
```
apiVersion: v1
kind: Secret
metadata:
  name: px-ibm
  namespace: portworx
type: Opaque
data:
  IBM_SERVICE_API_KEY: <base64_apikey>
  IBM_INSTANCE_ID: <base64_guid>
  IBM_CUSTOMER_ROOT_KEY: <base64_rootkey>
  IBM_BASE_URL: <base64_endpoint>
```
  metadata.name
  
  Enter px-ibm as the name for your Kubernetes secret. If you use a different name, Portworx does not recognize the secret during installation.
  
  data.IBM_SERVICE_API_KEY
  
  Enter the base64 encoded IBM Key Protect or Hyper Protect Crypto Services API key that you retrieved earlier.
  
  data.IBM_INSTANCE_ID
  
  Enter the base64 encoded service instance GUID that you retrieved earlier.
  
  data.IBM_CUSTOMER_ROOT_KEY
  
  Enter the base64 encoded root key that you retrieved earlier.
  
  data.IBM_BASE_URL
  
  IBM Key Protect: Enter the base64 encoded API endpoint of your service instance.
  
  Hyper Protect Crypto Services: Enter the base64 encoded Key Management public endpoint.
2. Create the secret in the portworx project of your cluster.
```
oc apply -f secret.yaml
```
3. Verify that the secret is created successfully.
```
oc get secrets -n portworx
```