Data encryption configuration¶

Overview¶

App Builder 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 App Builder 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. App Builder supports multiple, configurable key storage and encryption policies. Administrators must choose the appropriate policies for their environment.

Storage¶

App Builder supports the following key storage policies:

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

Encryption¶

Depending on the storage location, administrators should consider encrypting keys. App Builder 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 App Builder on startup for additional information.

Storage¶

File system¶

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

Settings¶

Example¶

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

Database¶

Keys can be stored in the App Builder 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, App Builder 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, App Builder 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¶

App Builder 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¶

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

Defaults¶

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

Cryptography providers¶

App Builder 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"
    }
  }
}