Data Encryption Configuration¶

Overview¶

Vinyl uses data encryption for two purposes:

• Protecting security tokens such as session cookies
• Application-level, column encryption

Both use the same underlying data encryption technology. Specifically, they use ASP.Net Data Protection API. Although Vinyl will attempt to configure the Data Protection library automatically, additional configuration may be necessary.

Data Encryption Keys¶

Data Encryption Keys (DEKs) are symmetric encryption keys used to protect data. Vinyl supports multiple, configurable key storage and encryption policies. Administrators must choose the appropriate policies for their environment.

Storage¶

Vinyl supports the following key storage policies:

• File system, either local or network share
• Database (3.3)
• Amazon Web Services (AWS) S3
• AWS Systems Manager Parameter Store (3.2)

Encryption¶

Depending on the storage location, administrators should consider encrypting keys. Vinyl supports the following key encryption policies:

• Certificate
• AWS Key Management Service

Configuration¶

Key storage and encryption policies are configured on startup. Configuration can be supplied using the appsettings.json file:

{
  "DataEncryption": {
    "KeyStorage": "FileSystem",
    "KeyEncryption": "None"
  }
}

Configuration can also be supplied by environment variables:

export DATAENCRYPTION__KEYSTORAGE=FileSystem
export DATAENCRYPTION__KEYENCRYPTION=None

See Configuring Vinyl on Startup for additional information.

Storage¶

File System¶

By default, Vinyl will store keys on the file system as plain text. They are stored in the keys directory beneath the Vinyl installation directory.

Settings¶

Example¶

{
  "DataEncryption": {
     "KeyStorage": "FileSystem",
     "Directory": "keys"
  }
}

Database¶

Keys can be stored in the Vinyl database. Note that, because the keys are used to encrypt data that's also stored in the database, the keys themselves should be encrypted.

Settings¶

Example¶

{
  "DataEncryption": {
     "KeyStorage": "Database",
     "KeyEncryption": "Certificate",
     "Certificate": "...base64-encoded...",
     "CertificatePassword": "password"
  }
}

AWS S3¶

EC2 instance local storage is not typically used for long-term persistence. As an alternative, Vinyl supports storing keys in S3 buckets.

Settings¶

Example¶

{
  "DataEncryption": {
     "KeyStorage": "S3",
     "S3BucketEndpoint": "https://{bucket}.s3{-aws-region}.amazonaws.com",
     "S3KeyPrefix": "production"
  }
}

AWS Systems Manager Parameter Store¶

EC2 instance local storage is not typically used for long-term persistence. As an alternative, keys can be stored in AWS Systems Manager Parameter Store. Keys stored in Parameter Store can be encrypted using Key Management Service (KMS).

Settings¶

Example¶

{
  "DataEncryption": {
     "KeyStorage": "ParameterStore",
     "ParameterNamePrefix": "/production",
     "KmsKeyId": "arn:aws:kms:us-east-1:1234567890:key/1234abcd-12ab-34cd-56ef-1234567890ab"
  }
}

Encryption¶

None¶

By default, Vinyl does not encrypt keys. However, keys may be encrypted transparently based on the storage policy. For example, an S3 bucket can be configured to encrypt all data.

Settings¶

Example¶

{
  "DataEncryption": {
    "KeyStorage": "FileSystem",
    "KeyEncryption": "None"
  }
}

Certificate¶

Keys can be encrypted using an X.509 certificate.

Settings¶

Example¶

{
  "DataEncryption": {
     "KeyStorage": "FileSystem",
     "CertificateThumbprint": "C123B3E899807189F11F0EC4AC320760F00ECE34"
  }
}

AWS Key Management Service¶

Vinyl can be configured to encrypt keys using AWS Key Management Service (KMS).

Settings¶

Example¶

{
  "DataEncryption": {
     "KeyStorage": "Database",
     "KeyEncryption": "Kms",
     "KmsKeyId": "arn:aws:kms:us-east-1:1234567890:key/1234abcd-12ab-34cd-56ef-1234567890ab"
  }
}

Amazon Web Services¶

S3 Bucket Policy¶

When storing encryption keys in an S3 bucket, consider using a role policy to grant the EC2 instance access to the bucket.

Example¶

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::{bucket-name}/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListAllMyBuckets",
                "s3:GetBucketLocation",
                "s3:ListBucket"
            ],
            "Resource": "*"
        }
    ]
}

KMS Key Policy¶

When encrypting keys with KMS, consider using a role policy to grant the EC3 instance access to the key.

Example¶

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "kms:GenerateDataKey",
      "kms:Encrypt",
      "kms:Decrypt"
    ],
    "Resource": [
      "arn:aws:kms:us-west-2:1234567890:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    ]
  }
}

Elastic Beanstalk¶

Vinyl ships with a .ebextensions script which automatically registers the environment properties.

Defaults¶

The default Elastic Beanstalk configuration varies based on the version of Vinyl.

Cryptography Providers¶

Vinyl is a .NET application. In .NET, cryptographic algorithm implementations may be supplied by one of three cryptography providers.

• Crypto Service Provider (CSP) - The Crypto Service Provider is a wrapper around the Windows Cryptography API (CAPI). CAPI has been deprecated. This provider is therefore not supported.
• Cryptography Next Generation (CNG) - Algorithms implemented by the CNG provider are typically FIPS compliant. This is the default cryptography provider.
• Managed - Algorithms implemented by this provider are not typically FIPS compliant. They may be slower than equivalent CNG implementations. However, managed implementations are shipped with .NET and are therefore available on all platforms.

Settings¶

Example¶

{
  "DataEncryption": {
    "CryptoProvider": "Managed"
  }
}

Import¶

Data encryption keys can be imported on startup. Typically, this is done to migrate keys from one storage location to another. Keys will be decrypted and encrypted in the process.

Settings¶

Example¶

{
  "DataEncryption": {
    "KeyStorage": "Database",
    "KeyEncryption": "Certificate",
    "Certificate": "...base64-encoded...",
    "CertificatePassword": "password",
    "Import": {
      "KeyStorage": "FileSystem"
      "Directory": "keys"
    }
  }
}