Encryption key stores

While JumpWire handles all of the orchestration for key management - including generation and rotation - an external key store is strongly recomended for production deployments. Relying on just the JumpWire engine can lead to keys being lost if the cluster is terminated.

There are several options for managing encryption keys, depending on your existing infrastructure and needs. Let us know if you're using something not listed below and we'll be happy to work with you!

JumpWire hosted (default)

Encryption keys can be stored through the JumpWire-hosted control plane. In this setup, the keys are further encrypted and stored in an internal Vault deployment. When an engine cluster connects to the control plane, the keys are retrieved and sent to the cluster.

HashiCorp Vault

Vault is enabled by providing authentication credentials to the engine at runtime. When the JumpWire engine is configured to use Vault, encryption keys are generated locally and stored in Vault's KV store. The path is configurable as part of the engine's startup configuration. Key rotation generates new keys and keeps both the new and old keys in Vault, allowing all keys to be retrieved for decrypting older data.

See the Vault Integration docs for more information.

AWS KMS

With AWS KMS, a master key is automatically generated in KMS if it doesn't already exist. On startup, the engine cluster will create a new data key encrypted with the master KMS key. Data fields are encrypted with the data key, and then the KMS-encrypted data key is prepended to the resulting text blob. If the engine tries to decrypt a value that it doesn't have a data key cached for, it will decrypt that key using KMS. This allows the cluster to startup without having any data keys initially available.

KMS can be enabled by setting JUMPWIRE_AWS_KMS_ENABLE=true. Optionally, the key to use can be configured by setting JUMPWIRE_AWS_KMS_KEY_NAMEto either a name to use as an alias prefix or the full key ID. This defaults to the value jumpwire.

The JumpWire engine must have appropriate AWS IAM permissions. Credentials can be provided using the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY or through the instance role without any additional configuration when running in ECS or EC2. The following IAM policy provides the minimum neccessary permissions.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey*",
                "kms:DescribeKey",
                "kms:Encrypt",
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:*:*:key/*",
            "Condition": {
                "ForAnyValue:StringLike": {
                    "kms:ResourceAliases": [
                        "alias/jumpwire/*"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "kms:*Alias",
            "Resource": "arn:aws:kms:*:*:alias/jumpwire/*"
        },
        {
            "Effect": "Allow",
            "Action": "kms:*Alias",
            "Resource": "arn:aws:kms:*:*:key/*"
        },
        {
            "Effect": "Allow",
            "Action": "kms:CreateKey",
            "Resource": "*"
        }
    ]
}

Restricting KMS operations to a specific key requires knowing the key ID in advance. This can be done by either manually creating the key first, or updating the policy after JumpWire generates the key.