// 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 an administrative process must create the encryption keys within AWS KMS, which
are used by the xref:con-topic-encryption-overview-{context}[envelope encryption] process.

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=$(aws secretsmanager get-random-password  --output text)
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.
----

[id='con-aws-kms-setup-policy-{context}']
== 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
----

== Establish an authentication mechanism for the filter

The filter must authenticate to AWS in order to perform envelope encryption operations, such as generating and decrypting DEKs.

include::proc-aws-kms-setup-application-identity-long-term.adoc[leveloffset=+1]
ifdef::include-aws-kms-service-config-identity-ec2-metadata[]
include::proc-aws-kms-setup-application-identity-ec2-metadata.adoc[leveloffset=+1]
endif::[]




