Portworx can integrate with AWS KMS to generate and use KMS Datakeys. This guide will get a Portworx cluster up which is connected to an AWS KMS endpoint. The Data Keys created in KMS can be used to encrypt Portworx Volumes.

Deploying Portworx

There are multiple ways in which you can setup Portworx so that it gets authenticated with AWS

Using AWS environment variables

Portworx can authenticate with AWS using AWS SDK’s EnvProvider.

Kubernetes users

If you are installing Portworx on Kubernetes, when generating the Portworx Kubernetes spec file:

  1. Use secretType=aws to specify the secret type as aws
  2. Use clusterSecretKey=<key> to set the cluster-wide secret ID. This kms data key associated with the secretID will be used as a passphrase for encrypting volumes.
  3. Use env=KEY1=VALUE1,KEY2=VALUE2 to set Portworx aws environment variables to identify AWS endpoint.

Instructions on generating the Portworx spec for Kubernetes are available here.

If you already have a running Portworx installation, update /etc/pwx/config.json on each node.

Docker & Docker plugin users

If you are installing Portworx as a Docker container or a plugin,

  1. Use -secret_type aws -cluster_secret_key <secret-id> when starting Portworx to specify the secret type as AWS and the cluster-wide secret ID. This kms data key associated with the secretID will be used as a passphrase for encrypting volumes.
  2. Use -e docker option to expose the Portworx AWS KMS environment variables

If you already have a running Portworx installation, update /etc/pwx/config.json on each node.

Portworx AWS KMS environment variables

  • AWS_ACCESS_KEY_ID=<aws-access-key> : Sets the AWS_ACCESS_KEY_ID environment variable. It would be used to authenticate with AWS.
  • AWS_SECRET_ACCESS_KEY=<aws-secret-key> : Sets the AWS_SECRET_ACCESS_KEY environment variable. It would be used to authenticate with AWS.
  • AWS_SECRET_TOKEN_KEY=<aws-secret-token> : Sets the AWS_SECRET_TOKEN_KEY environment variable. It would be used to authenticate with AWS.
  • AWS_CMK=<kms-customer-master-key> : Sets the AWS_CMK environment variable. The customer master key is used while generating KMS Data keys for encrypting volumes.
  • AWS_REGION=<aws-region> : Sets the AWS_REGION environment variable. This is the AWS region where the customer master key was created.

Adding AWS KMS Credentials to config.json

Note:
This section is optional and is only needed if you intend to provide the PX configuration before installing PX.

If you are deploying PX with your PX configuration created before hand, then add the following secrets section to the /etc/pwx/config.json:

# cat /etc/pwx/config.json
{
    "clusterid": "<cluster-id>",
    "secret": {
        "secret_type": "aws",
        "cluster_secret_key": "mysecret",
    }
    ...
}

Using AWS EC2 Role Credentials

Portworx can authenticate with AWS using AWS SDK’s EC2RoleCredentials Provider. Follow these instructions to create an EC2 role. Make sure you provide the following access to KMS in your policy associated with EC2 role.

Here is a sample AWS Policy that gives access to KMS

{
    "Version": "2012-10-17",
    "Statement": [
            {
	                "Sid": "Stmt1490047200000",
            "Effect": "Allow",
            "Action": [
	                    "kms:*"
            ],
            "Resource": [
                "arn:aws:kms:us-east-1:<aws-id>:key/<key-id>"
            ]
        }
    ]
}

Apply EC2 role to all the AWS instances where Portworx will be running.

You can start PX on all the EC2 nodes using the above docker run command and ignoring the environment variables.

Using PX CLI to authenticate with AWS

If you do not wish to set AWS environment variables, you can authenticate PX with AWS using PX CLI. Run the following commands:

# pxctl secrets aws login
Enter AWS_ACCESS_KEY_ID [Hit Enter to ignore]: ********************
Enter AWS_SECRET_ACCESS_KEY [Hit Enter to ignore]: ****************************************
Enter AWS_SECRET_TOKEN_KEY [Hit Enter to ignore]:
Enter AWS_CMK [Hit Enter to ignore]: ***********************
Enter AWS_REGION [Hit Enter to ignore]: us-east-1
Successfully authenticated with AWS.

Important: You need to run this command on all PX nodes, so that you could create and mount encrypted volumes on all nodes

If the CLI is used to authenticate with AWS, for every restart of PX container it needs to be re-authenticated by running the login command.

Key generation with AWS KMS

The following sections describe the key generation process with PX and AWS KMS. These keys can be used as passphrases for encrypted volumes. More info about encrypted volumes here

Using AWS CLI

You can follow the instructions here to generate a data key.

$ aws-cli generate-data-key-without-plaintext --key-id <cmk> --key_spec <AES_256/AES_128>

The above command will return the following two outputs

  • CiphertextBlob -> (blob): The encrypted data encryption key.
  • KeyId -> (string): The identifier of the CMK under which the data encryption key was generated and encrypted

Store the ciphertext blob in a file on the host. Provide this file as an input secret key while creating encrypted volumes.

Important: You need to write the ciphertext blob in a file which is accessible by the PX container. We recommend /var/lib/osd/secrets/

Here is an example of creating an encrypted volume using such a file

$ pxctl volume create --secure --secret_key /var/lib/osd/secrets/aws_cipher_blob.txt --size 20 encrypted_volume

Using PX

If you do not wish to pre-generate data keys using AWS CLI you can delegate this action to Portworx, and PX will generate the kms data keys for you.

PX associates each kms data key with a unique keyID that you provide while creating the encrypted volume. You can use this keyID for subsequent operations which require you to provide the secret_key.

Here is an example of creating an encrypted volume using a unique keyID

$ pxctl volume create --secure --secret_key my_secret_key --size 20 encrypted_volume

The above command generates a kms data key and associates it with the keyID my_secret_key. For subsequent operations you can use the same keyID

$ pxctl host attach --secret_key my_secret_key encrypted_volume

Setting cluster wide secret key

A cluster wide secret key is a common key that can be used to encrypt all your volumes. You can set the cluster secret key using the following command

# /opt/pwx/bin/pxctl secrets set-cluster-key
Enter cluster wide secret key: *****
Successfully set cluster secret key!

As an input to set-cluster-key command you have the following two options

  1. Provide the path to the pre-generated kms data key. PX will not generate a key if a valid path and a valid kms cipher blob text is provided.

  2. Provide a keyID. If the keyID was previously used, the already generated kms data key will be set as the cluster wide secret key. If the keyID was never used before a new kms data key will be generated and set as the cluster wide secret key.