// file included in the following:
//
// assembly-aws-kms.adoc

[id='con-aws-kms-setup-{context}']
= Establish an aliasing convention for keys within AWS KMS

The filter references KEKs within AWS via an {aws}/kms/latest/developerguide/alias-about.html[AWS key alias].

Establish a naming convention for key aliases to keep the filter’s keys separate from those used by other systems.
Here, we use a prefix of KEK_ for filter aliases.
Adjust the instructions if a different naming convention is used.

== Role of the administrator

To use the filter, an administrator (or administrative process) must create the encryption keys within AWS KMS that will be used to encrypt the records.
The organization deploying the Record Encryption filter is responsible for managing this administrator or process.

The administrator must have permissions to create keys in AWS KMS.
As a starting point, the built-in AWS policy `AWSKeyManagementServicePowerUser` confers sufficient key management privileges.

To get started, use the following commands to set up an administrator with permissions suitable for managing encryption keys in KMS through an AWS Cloud Shell.
This example illustrates using the user name`kroxylicious-admin`, but you can choose a different name if preferred.  
Adjust the instructions accordingly if you use a different user name.

[source,shell]
----
ADMIN=kroxylicious-admin
INITIAL_PASSWORD=$(tr -dc 'A-Za-z0-9!?%=' < /dev/urandom | head -c 10)
CONSOLE_URL=https://$(aws sts get-caller-identity --query Account --output text).signin.aws.amazon.com/console
aws iam create-user --user-name ${ADMIN}
aws iam attach-user-policy --user-name ${ADMIN} --policy-arn arn:aws:iam::aws:policy/AWSKeyManagementServicePowerUser
aws iam attach-user-policy --user-name ${ADMIN} --policy-arn arn:aws:iam::aws:policy/IAMUserChangePassword
aws iam attach-user-policy --user-name ${ADMIN} --policy-arn arn:aws:iam::aws:policy/AWSCloudShellFullAccess
aws iam create-login-profile --user-name ${ADMIN} --password ${INITIAL_PASSWORD} --password-reset-required
echo Now log in at ${CONSOLE_URL}  with user name ${ADMIN} password ${INITIAL_PASSWORD} and change the password.
----

== Establish an application identity for the filter

The filter must authenticate to AWS in order to perform envelope encryption operations, such as generating and decrypting DEKs. 
Therefore, an AWS IAM identity with sufficient permissions must be created for the filter.

Use AWS IAM to create this identity and generate an *Access Key* for it. 
The Access Key/Secret Key pair is used by the filter. 
Do not enable console access for this user.

Using the CLI, the following commands create the IAM identity for the filter. 
This example uses the user name `kroxylicious`, but you can choose a different name if needed. 
Adjust the instructions accordingly if using a different user name.

[source,shell]
----
aws iam create-user --user-name kroxylicious
aws iam create-access-key --user-name kroxylicious
----

== Create an alias-based policy for KEK aliases

Create an alias based policy granting permissions to use keys aliased by the established alias naming convention.

[source,shell]
----
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
cat > /tmp/policy << EOF
{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "AliasBasedIAMPolicy",
			"Effect": "Allow",
			"Action": [
				"kms:Encrypt",
				"kms:Decrypt",
				"kms:GenerateDataKey*",
				"kms:DescribeKey"
			],
			"Resource": [
                "arn:aws:kms:*:${AWS_ACCOUNT_ID}:key/*"
			],
			"Condition": {
				"ForAnyValue:StringLike": {
					"kms:ResourceAliases": "alias/KEK_*"
				}
			}
		}
	]
}
EOF
aws iam create-policy --policy-name KroxyliciousRecordEncryption --policy-document file:///tmp/policy
----

== Apply the alias-based policy to the filter's application identity

Attach the alias policy to the filter's application identity. 
This will allow the filter to perform key operations on all KEKs with aliases that match the specified naming convention.

[source,shell]
----
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
aws iam attach-user-policy --user-name kroxylicious --policy-arn "arn:aws:iam::${AWS_ACCOUNT_ID}:policy/KroxyliciousRecordEncryption"
----
