feat(kms): trustAccountIdentities avoids cyclic stack dependencies

packages/@aws-cdk/aws-kms/README.md

@@ -29,6 +29,8 @@ key.addAlias('alias/bar');
 
 ### Sharing keys between stacks
 
+> see Trust Account Identities for additional details
+
 To use a KMS key in a different stack in the same CDK application,
 pass the construct to the other stack:
 
@@ -37,6 +39,8 @@ pass the construct to the other stack:
 
 ### Importing existing keys
 
+> see Trust Account Identities for additional details
+
 To use a KMS key that is not defined in this CDK app, but is created through other means, use
 `Key.fromKeyArn(parent, name, ref)`:
 
@@ -50,3 +54,72 @@ myKeyImported.addAlias('alias/foo');
 Note that a call to `.addToPolicy(statement)` on `myKeyImported` will not have
 an affect on the key's policy because it is not owned by your stack. The call
 will be a no-op.
+
+### Trust Account Identities
+
+KMS keys can be created to trust IAM policies. This is the default behavior in
+the console and is described
+[here](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html).
+This same behavior can be enabled by:
+
+```ts
+new Key(stack, 'MyKey', { trustAccountIdentities: true });
+```
+
+Using `trustAccountIdentities` solves many issues around cyclic dependencies
+between stacks. The most common use case is creating an S3 Bucket with CMK
+default encryption which is later accessed by IAM roles in other stacks.
+
+stack-1 (bucket and key created)
+
+```ts
+// ... snip
+const myKmsKey = new kms.Key(this, 'MyKey', { trustAccountIdentities: true });
+
+const bucket = new Bucket(this, 'MyEncryptedBucket', {
+    bucketName: 'myEncryptedBucket',
+    encryption: BucketEncryption.KMS,
+    encryptionKey: myKmsKey
+});
+```
+
+stack-2 (lambda that operates on bucket and key)
+
+```ts
+// ... snip
+
+const fn = new lambda.Function(this, 'MyFunction', {
+  runtime: lambda.Runtime.NODEJS_10_X,
+  handler: 'index.handler',
+  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
+});
+
+const bucket = s3.Bucket.fromBucketName(this, 'BucketId', 'myEncryptedBucket');
+
+const key = kms.Key.fromKeyArn(this, 'KeyId', 'arn:aws:...'); // key ARN passed via stack props
+
+bucket.grantReadWrite(fn);
+key.grantEncryptDecrypt(fn);
+```
+
+The challenge in this scenario is the KMS key policy behavior. The simple way to understand 
+this, is IAM policies for account entities can only grant the permissions granted to the
+account root principle in the key policy. When `trustAccountIdentities` is true,
+the following policy statement is added:
+
+```json
+{
+  "Sid": "Enable IAM User Permissions",
+  "Effect": "Allow",
+  "Principal": {"AWS": "arn:aws:iam::111122223333:root"},
+  "Action": "kms:*",
+  "Resource": "*"
+}
+```
+
+As the name suggests this trusts IAM policies to control access to the key.
+If account root does not have permissions to the specific actions, then the key
+policy and the IAM policy for the entity (e.g. Lambda) both need to grant
+permission.
+
+

packages/@aws-cdk/aws-kms/lib/key.ts

@@ -73,6 +73,14 @@ abstract class KeyBase extends Resource implements IKey {
    */
   protected abstract readonly policy?: iam.PolicyDocument;
 
+  /**
+   * Optional property to control trusting account identities.
+   *
+   * If specified grants will default identity policies instead of to both
+   * resource and identity policies.
+   */
+  protected abstract readonly trustAccountIdentities: boolean;
+
   /**
    * Collection of aliases added to the key
    *
@@ -130,19 +138,25 @@ abstract class KeyBase extends Resource implements IKey {
     const crossAccountAccess = this.isGranteeFromAnotherAccount(grantee);
     const crossRegionAccess = this.isGranteeFromAnotherRegion(grantee);
     const crossEnvironment = crossAccountAccess || crossRegionAccess;
-    return iam.Grant.addToPrincipalAndResource({
+    const grantOptions: iam.GrantWithResourceOptions = {
       grantee,
       actions,
       resource: this,
-      resourcePolicyPrincipal: principal,
-
-      // if the key is used in a cross-environment matter,
-      // we can't access the Key ARN (they don't have physical names),
-      // so fall back to using '*'. ToDo we need to make this better... somehow
-      resourceArns: crossEnvironment ? ['*'] : [this.keyArn],
-
+      resourceArns: [this.keyArn],
       resourceSelfArns: crossEnvironment ? undefined : ['*'],
-    });
+    };
+    if (this.trustAccountIdentities) {
+      return iam.Grant.addToPrincipalOrResource(grantOptions);
+    } else {
+      return iam.Grant.addToPrincipalAndResource({
+        ...grantOptions,
+        // if the key is used in a cross-environment matter,
+        // we can't access the Key ARN (they don't have physical names),
+        // so fall back to using '*'. ToDo we need to make this better... somehow
+        resourceArns: crossEnvironment ? ['*'] : [this.keyArn],
+        resourcePolicyPrincipal: principal,
+      });
+    }
   }
 
   /**
@@ -268,6 +282,18 @@ export interface KeyProps {
    * @default RemovalPolicy.Retain
    */
   readonly removalPolicy?: RemovalPolicy;
+
+  /**
+   * Whether the key usage can be granted by IAM policies
+   *
+   * Setting this to true adds a default statement which delegates key
+   * access control completely to the identity's IAM policy (similar
+   * to how it works for other AWS resources).
+   *
+   * @default false
+   * @see https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-root-enable-iam
+   */
+  readonly trustAccountIdentities?: boolean;
 }
 
 /**
@@ -288,6 +314,10 @@ export class Key extends KeyBase {
       public readonly keyArn = keyArn;
       public readonly keyId: string;
       protected readonly policy?: iam.PolicyDocument | undefined = undefined;
+      // defaulting true: if we are importing the key the key policy is
+      // undefined and impossible to change here; this means updating identity
+      // policies is really the only option
+      protected readonly trustAccountIdentities: boolean = true;
 
       constructor(keyId: string) {
         super(scope, id);
@@ -307,14 +337,16 @@ export class Key extends KeyBase {
   public readonly keyArn: string;
   public readonly keyId: string;
   protected readonly policy?: iam.PolicyDocument;
+  protected readonly trustAccountIdentities: boolean;
 
   constructor(scope: Construct, id: string, props: KeyProps = {}) {
     super(scope, id);
 
-    if (props.policy) {
-      this.policy = props.policy;
+    this.policy = props.policy || new iam.PolicyDocument();
+    this.trustAccountIdentities = props.trustAccountIdentities || false;
+    if (this.trustAccountIdentities) {
+      this.allowAccountIdentitiesToControl();
     } else {
-      this.policy = new iam.PolicyDocument();
       this.allowAccountToAdmin();
     }
 
@@ -334,8 +366,17 @@ export class Key extends KeyBase {
     }
   }
 
+  private allowAccountIdentitiesToControl() {
+    this.addToResourcePolicy(new iam.PolicyStatement({
+      resources: ['*'],
+      actions: ['kms:*'],
+      principals: [new iam.AccountRootPrincipal()]
+    }));
+
+  }
   /**
-   * Let users from this account admin this key.
+   * Let users or IAM policies from this account admin this key.
+   * @link https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default
    * @link https://aws.amazon.com/premiumsupport/knowledge-center/update-key-policy-future/
    */
   private allowAccountToAdmin() {