aws_kms_key Resource

Use the aws_kms_key InSpec audit resource to test properties of a single AWS KMS Key.

AWS Key Management Service (AWS KMS) is a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data. AWS KMS lets you create master keys that can never be exported from the service and which can be used to encrypt and decrypt data based on policies you define.

Each AWS KMS Key is uniquely identified by its key_id or arn.

For additional information, including details on parameters and properties, see the AWS documentation on KS Keys.

Install

This resource is available in the Chef InSpec AWS resource pack.

For information on configuring your AWS environment for Chef InSpec and creating an InSpec profile that uses the InSpec AWS resource pack, see the Chef InSpec documentation on the AWS cloud platform.

Syntax

An aws_kms_key resource block identifies a key by key_arn or the key id.

# Find a kms key by arn

describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
  it { should exist }
end

# Find a kms key by just the id

describe aws_kms_key('4321dcba-21io-23de-85he-ab0987654321') do
  it { should exist }
end

# Hash syntax for key arn

describe aws_kms_key(key_id: 'arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
  it { should exist }
end

Parameters

alias (required if key_id not specified)

This resource accepts searching for a KMS Key by it’s Alias. This can be passed as a alias: 'alias/value' key-value entry in a hash. This will then use the target_key_id from the Alias to search for the KMS Key.

key_id (required if alias not specified)

This resource accepts searching for a KMS Key by the KMS Key ID which can represent both the actual Key ID or the ARN of the Key. This can be passed either as a string or as a key_id: 'value' key-value entry in a hash.

Properties

key_id

The globally unique identifier for the key.

arn

The ARN identifier of the specified key.

creation_date

Specifies the date and time when the key was created.

created_days_ago

Specifies the number of days since the key was created.

key_state

Specifies the state of the key one of “Enabled”, “Disabled”, “PendingDeletion”, “PendingImport”. To just check if the key is enabled or not, use the be_enabled matcher.

description

The description of the key.

deletion_time

Specifies the date and time after which AWS KMS deletes the key. This value is present only when KeyState is PendingDeletion, otherwise this value is nil.

invalidation_time

Provides the date and time until the key is not valid. Once the key is not valid, AWS KMS deletes the key and it becomes unusable. This value will be null unless the keys Origin is EXTERNAL and its matcher have_key_expiration is set to true.

tags

A hash with each key-value pair corresponding to a tag associated with the entity.

Examples

Test that the specified key does exist.

describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
  it { should exist }
end

Test that the specified key is enabled.

describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
  it { should be_enabled }
end

Test that the specified key is rotation enabled.

describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
  it { should have_rotation_enabled }
end

Makes sure that the key was created at least 10 days ago.

describe aws_kms_key('arn:aws:kms:us-east-1::key/4321dcba-21io-23de-85he-ab0987654321') do
  its('creation_date') { should be < Time.now - 10 * 86400 }
end

Matchers

This InSpec audit resource has the following special matchers. For a full list of available matchers (such as exist) please visit our matchers page.

Use should_not to test the entity should not exist in all cases.

exist

The control will pass if the describe returns at least one result.

it { should exist }

it { should_not exist }

be_enabled

The test will pass if the specified key’s key_state is set to enabled.

it { should be_enabled }

be_external

Provides whether the source of the key’s key material is external or not. If it is not external than it was created by AWS KMS. When it is external, the key material was imported from an existing key management infrastructure or the key lacks key material.

it { should be_external }

be_managed_by_aws

Provides whether or not the key manager is from AWS. If it is not managed by AWS, it is managed by the customer.

it { should be_managed_by_aws }

have_key_expiration

Specifies whether the key’s key material expires. This value is null unless the keys Origin is External.

it { should have_key_expiration }

have_rotation_enabled

The test will pass if automatic rotation of the key material is enabled for the specified key.

it { should have_rotation_enabled }

AWS Permissions

Your Principal will need the KMS:Client:DescribeKeyResponse, and KMS:Client:GetKeyRotationStatusResponse actions set to allow.

You can find detailed documentation at Actions, Resources, and Condition Keys for AWS Key Management Service.