Customer managed encryption key (CMEK)

Veracode uses a root encryption key to encrypt your data and assets that are transmitted across networks for security scans. For each asset, such as binary uploads and PDF reports of scan results, Veracode generates a data key from the root encryption key to encrypt and decrypt the corresponding asset at various stages of security testing.

Veracode Customer Managed Encryption Key (CMEK) provides an additional level of isolation and control over your assets by giving you the option to provide your own root encryption key. When CMEK is enabled, Veracode uses your root encryption key instead of Veracode's key. You manage your root key within your environment and you can revoke access to assets secured by it at any time.

CMEK is particularly important when regulatory requirements or internal policy require you to maintain greater control over how your assets are secured and how quickly access can be revoked.

CMEKs encrypt the following data:

• Packaged application binaries uploaded to the Veracode Platform
• Results and index files generated by the Veracode Platform
• Downloadable PDF reports generated by the Veracode Platform

Prerequisites and limitations

Veracode CMEK uses a root encryption key located and managed in the key management system of your environment.

Veracode CMEK currently supports only the AWS key management system.

Caution

CMEK relies on access policies configured in your AWS environment. As the customer, you are responsible for ensuring that you provide only the required access to Veracode and inhibit the exposure of other AWS Key Management Service (KMS) secrets or assets in the account.

In AWS, select an AWS region according to the following table or an AWS region geographically nearest to the Veracode account region.

Veracode account region	AWS region
US	us-east-1
EU	eu-central-1

To select an AWS region:

1. Log into your AWS account.
2. Locate the AWS banner on the top of the AWS page.
3. The option to select a region is on the right side of the banner.

Activate Customer Managed Encryption Key

To activate Customer Managed Encryption Key, contact your Veracode customer support manager.

Set up Customer Managed Encryption Key

To setup CMEK, complete the following tasks:

1. Configure user and permissions in AWS KMS
2. Configure a root encryption key
3. Enable the Veracode Platform to access the AWS account
4. Configure a new Veracode application to use CMEK
5. Reconfigure an application to use CMEK
6. Validate CMEK configuration

Configure user and permissions in AWS KMS

For Veracode to access your root encryption key, you must provision an AWS IAM user with the required permissions.

To complete this task:

1. Create an AWS IAM Policy
2. Attach the IAM policy to an AWS IAM user
3. Generate access credentials for the IAM user

Create an AWS IAM policy

1. Sign in to your AWS account.

2. Under Console Home, select IAM.

3. Under Access Management, select Policies.

4. Select Create policy.

5. For Policy editor, select JSON.

6. Copy the JSON policy below and paste it into the policy editor:

   {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:Encrypt",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:DescribeKey"
            ],
            "Resource": "*"
           }
    ]
   }
   Important

   You must review the IAM policy to ensure that it provides only the necessary access to Veracode to enable CMEK, prohibits unnecessary actions, inhibits the exposure of unrelated information, and complies with your security policies and practices.

7. Select Next. The Review and create page opens.

8. For Policy name, enter a policy name.

9. Select Create policy.

Attach the IAM policy to an AWS IAM user

In this step, create an AWS IAM user and attach the policy you created to the user.

1. Sign in to your AWS account.

2. Under Console Home, select IAM.

3. Select Create user.

4. For User name, enter a user name.

   Important

   Veracode recommends that this user is not provided access to the AWS Management console. So, do not select Provide user access to the AWS Management console.

5. Select Next. The Set permissions page opens.

6. Under Permissions options, select Attach policies directly.

7. Under Permissions policies, search for the policy that you created.

8. Select your policy and then select Next.

9. Select Create user.

Generate access credentials for the IAM user

1. Log into your AWS account.
2. Under Console Home, select IAM.
3. Select the user you created.
4. Select the Security credentials tab.
5. Under Access keys, select Create access key.
6. In Access key best practices & alternatives, under Use case, select Application running outside AWS. Then, select Next.
7. In Set description, you may optionally provide a tag. Then, select Next.
8. In Retrieve access keys, you will find the Access key and Secret access key. Select Show under Secret access key to see the key.
9. Copy the access key and the secret access key and save it in a secure location. The only time the access key and secret access key is available is when you are creating it. Hence, make sure that you save this in a secure location.
10. Select Done. The user information page is displayed.

Configure a root encryption key

You may use an AWS-generated key to create the root key, or create the root key using a key that has been generated outside AWS KMS. If you decide to use a key that is generated outside AWS, ensure you have the key before proceeding.

To complete this task:

1. Sign in to your AWS account.

2. Under Console Home, select Key Management Service.

3. Select Create key. The Configure key page opens.

4. Select the options in one of the following tables based on whether you want to generate a root key from a new AWS KMS key or an external key:

   If you decide to use an AWS-generated key to create the root key, use the options in the following table:

   Key type	Key usage	Advanced options, Key material origin	Regionality
   Symmetric	Encrypt and Decrypt	KMS – recommended	Single-Region key

   If you decide to use an external key to create the root key, use the options in the following table:

   Key type	Key usage	Advanced options, Key material origin	Regionality
   Symmetric	Encrypt and Decrypt	External (Import Key material)	Single-Region key

   Follow the guidelines provided by AWS for using an external key.

5. Select Next. The Add labels page opens.

6. Enter an alias. Optionally, you can provide a description and assign tags based on your organization’s policies.

7. Select Next. The Define key administrative permissions - Optional page opens.

8. Under Key administrators, select the AWS administrative user who is allowed to manage the key.

9. Under Key deletion, select Allow key administrators to delete this key.

10. Select Next. The Define key usage permissions - Optional page opens. Select AWS IAM user that we created earlier. This is the user who will use this key.

11. Select Next. The Edit key policy - optional page opens. Review the policy key to ensure the correct permissions and restrictions are in place for using the key securely.

[Caution]

You must review the KMS Key policy to ensure that it provides only the required access to Veracode to enable CMEK, prohibits unnecessary actions, inhibits the exposure of unrelated information, and complies with your security policies and practices.

12. Select Next. The Review page opens.
13. Review the KMS key configuration, and then select Finish.

You have completed generating the root key. Save the alias of the AWS key to a secure location. You will need it to configure Veracode applications to use CMEK.

Enable the Veracode Platform to access the AWS account

After you have configured user permissions, generated access credentials, and configured the root key, the next step is to contact Veracode support to enable CMEK on the Veracode Platform. Veracode support will request the following information to enable the Veracode Platform to access the root encryption key stored in your AWS KMS:

• Access key
• Secret access key
• AWS region
• AWS account

After you provide this information, Veracode will configure the Veracode Platform to access the root encryption key stored in AWS KMS.

Configure a new Veracode application to use CMEK

To configure a new Veracode application to use Customer Managed Encryption Key (CMEK), run the application profile creation API with the field custom_kms_alias in the payload.

Important

You can enable CMEK for a new application only using the Veracode REST API. You cannot do this from the Veracode Platform user interface. If you set up a new application from the Veracode Platform user interface, it will always use Veracode Managed Key.

The field custom_kms_alias is a key-value pair that takes the alias of the root key as the input.

In the following code snippet from the application creation REST API, the custom_kms_alias field takes the alias of the root key (string datatype) as the input.

"custom_fields": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "custom_kms_alias": "string",
    "description": "string",
    "name": "string",
    "policies": [
      {
        "guid": "string",
        "is_default": true,
        "name": "string",
        "policy_compliance_status": "DETERMINING"
      }
    ],

Reconfigure an application to use CMEK

You can reconfigure applications that use Veracode Managed Key to, instead, use CMEK.

To reconfigure an existing application to use CMEK, complete the same steps as configuring a new Veracode application to use CMEK.

After you configure an existing application to use CMEK, all new assets will be encrypted using the CMEK. In addition, the key rotation process will be initiated to encrypt all existing assets, that were previously encrypted with Veracode Managed Key, with the new CMEK.

To display applications that use Veracode Managed key, in Analytics, create a query that will show the Custom KMS Alias for applications. Then, apply a filter to display only applications that have an empty Custom CMK Alias field. Refer Validate CMEK configuration.

Validate CMEK configuration

You can validate that CMEK has been properly configured on an application using Analytics.

To complete this task:

1. In the Veracode Platform, select Analytics and then select Explore Your Data.

2. Under Explore Your Data, select Applications.

3. Create a query that will show the Custom KMS Alias for applications. To do so, select the dimensions Application ID, Application Name and Custom KMS Alias.

4. To display only applications with a CMK alias, use the Filters option.

   

5. To run the query, select Run.

   If the custom KMS alias is configured properly for an application, you will see your application displayed along with the corresponding custom KMS alias.

Rotate your key

You should periodically rotate or change your CMEK as per the requirements of your regulatory, compliance, or internal policy.

To rotate your CMEK, configure a new root encryption key and reconfigure your applications to use the new root encryption key.

Revoke access to CMEK

You can temporarily withhold or permanently revoke Veracode access to your assets stored on the Veracode Platform. However, be careful to ensure that you do not unintentionally permanently revoke access to your assets.

Important

Veracode cannot recover your root key or your assets on Veracode platform if you intentionally or unintentionally delete your AWS KMS root key and revoke access.

If you don't properly configure AWS KMS key and access permissions for applications that use CMEK, Veracode cannot provide support for these applications.

CMEK only encrypts specific types of data on the Veracode Platform. If you want all data in your account to be encrypted, contact Veracode Support.

The following table shows the actions that you can perform on your root key to revoke access. It also displays the result of each action, and how you may be able to undo the action.

Action	Effect	Recovery procedure
Delete AWS KMS key	Permanent access revocation	You cannot undo this action unless you cancel the scheduled key deletion within the configured waiting period.
Disable AWS KMS key	Temporary access revocation	Your AWS KMS administrator can enable the key again in AWS KMS.
Remove IAM permissions from the AWS IAM user	Temporary access revocation	You can provide the IAM permissions to the AWS IAM user again.
Remove access credentials from the AWS IAM user	Temporary access revocation	You can create new access credentials for the AWS IAM user and provide them to Veracode Support.