See: Description
Interface | Description |
---|---|
AliasAttributes |
Properties of a reference to an existing KMS Alias.
|
AliasProps |
Construction properties for a KMS Key Alias object.
|
CfnAliasProps |
Properties for defining a `CfnAlias`.
|
CfnKeyProps |
Properties for defining a `CfnKey`.
|
CfnReplicaKeyProps |
Properties for defining a `CfnReplicaKey`.
|
IAlias |
A KMS Key alias.
|
IAlias.Jsii$Default |
Internal default implementation for
IAlias . |
IKey |
A KMS Key, either managed by this CDK app, or imported.
|
IKey.Jsii$Default |
Internal default implementation for
IKey . |
KeyLookupOptions |
Properties for looking up an existing Key.
|
KeyProps |
Construction properties for a KMS Key object.
|
Class | Description |
---|---|
Alias |
Defines a display name for a customer master key (CMK) in AWS Key Management Service (AWS KMS).
|
Alias.Builder |
A fluent builder for
Alias . |
AliasAttributes.Builder |
A builder for
AliasAttributes |
AliasAttributes.Jsii$Proxy |
An implementation for
AliasAttributes |
AliasProps.Builder |
A builder for
AliasProps |
AliasProps.Jsii$Proxy |
An implementation for
AliasProps |
CfnAlias |
A CloudFormation `AWS::KMS::Alias`.
|
CfnAlias.Builder |
A fluent builder for
CfnAlias . |
CfnAliasProps.Builder |
A builder for
CfnAliasProps |
CfnAliasProps.Jsii$Proxy |
An implementation for
CfnAliasProps |
CfnKey |
A CloudFormation `AWS::KMS::Key`.
|
CfnKey.Builder |
A fluent builder for
CfnKey . |
CfnKeyProps.Builder |
A builder for
CfnKeyProps |
CfnKeyProps.Jsii$Proxy |
An implementation for
CfnKeyProps |
CfnReplicaKey |
A CloudFormation `AWS::KMS::ReplicaKey`.
|
CfnReplicaKey.Builder |
A fluent builder for
CfnReplicaKey . |
CfnReplicaKeyProps.Builder |
A builder for
CfnReplicaKeyProps |
CfnReplicaKeyProps.Jsii$Proxy |
An implementation for
CfnReplicaKeyProps |
IAlias.Jsii$Proxy |
A proxy class which represents a concrete javascript instance of this type.
|
IKey.Jsii$Proxy |
A proxy class which represents a concrete javascript instance of this type.
|
Key |
Defines a KMS key.
|
Key.Builder |
A fluent builder for
Key . |
KeyLookupOptions.Builder |
A builder for
KeyLookupOptions |
KeyLookupOptions.Jsii$Proxy |
An implementation for
KeyLookupOptions |
KeyProps.Builder |
A builder for
KeyProps |
KeyProps.Jsii$Proxy |
An implementation for
KeyProps |
ViaServicePrincipal |
A principal to allow access to a key if it's being used through another AWS service.
|
Enum | Description |
---|---|
KeySpec |
The key spec, represents the cryptographic configuration of keys.
|
KeyUsage |
The key usage, represents the cryptographic operations of keys.
|
---
Define a KMS key:
Key.Builder.create(this, "MyKey") .enableKeyRotation(true) .build();
Define a KMS key with waiting period:
Specifies the number of days in the waiting period before AWS KMS deletes a CMK that has been removed from a CloudFormation stack.
Key key = Key.Builder.create(this, "MyKey") .pendingWindow(Duration.days(10)) .build();
Add a couple of aliases:
Key key = new Key(this, "MyKey"); key.addAlias("alias/foo"); key.addAlias("alias/bar");
Define a key with specific key spec and key usage:
Valid keySpec
values depends on keyUsage
value.
Key key = Key.Builder.create(this, "MyKey") .keySpec(KeySpec.ECC_SECG_P256K1) // Default to SYMMETRIC_DEFAULT .keyUsage(KeyUsage.SIGN_VERIFY) .build();
To use a KMS key in a different stack in the same CDK application, pass the construct to the other stack:
/** * Stack that defines the key */ public class KeyStack extends Stack { public final Key key; public KeyStack(App scope, String id) { this(scope, id, null); } public KeyStack(App scope, String id, StackProps props) { super(scope, id, props); this.key = Key.Builder.create(this, "MyKey").removalPolicy(RemovalPolicy.DESTROY).build(); } } public class UseStackProps extends StackProps { private IKey key; public IKey getKey() { return this.key; } public UseStackProps key(IKey key) { this.key = key; return this; } } /** * Stack that uses the key */ public class UseStack extends Stack { public UseStack(App scope, String id, UseStackProps props) { super(scope, id, props); // Use the IKey object here. // Use the IKey object here. Alias.Builder.create(this, "Alias") .aliasName("alias/foo") .targetKey(props.getKey()) .build(); } } KeyStack keyStack = new KeyStack(app, "KeyStack"); new UseStack(app, "UseStack", new UseStackProps().key(keyStack.getKey()));
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)
:
IKey myKeyImported = Key.fromKeyArn(this, "MyImportedKey", "arn:aws:..."); // you can do stuff with this imported key. myKeyImported.addAlias("alias/foo");
Note that a call to .addToResourcePolicy(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.
If a Key has an associated Alias, the Alias can be imported by name and used in place of the Key as a reference. A common scenario for this is in referencing AWS managed keys.
import software.amazon.awscdk.services.cloudtrail.*; IAlias myKeyAlias = Alias.fromAliasName(this, "myKey", "alias/aws/s3"); Trail trail = Trail.Builder.create(this, "myCloudTrail") .sendToCloudWatchLogs(true) .kmsKey(myKeyAlias) .build();
Note that calls to addToResourcePolicy
and grant*
methods on myKeyAlias
will be
no-ops, and addAlias
and aliasTargetKey
will fail, as the imported alias does not
have a reference to the underlying KMS Key.
If you can't use a KMS key imported by alias (e.g. because you need access to the key id), you can lookup the key with Key.fromLookup()
.
In general, the preferred method would be to use Alias.fromAliasName()
which returns an IAlias
object which extends IKey
. However, some services need to have access to the underlying key id. In this case, Key.fromLookup()
allows to lookup the key id.
The result of the Key.fromLookup()
operation will be written to a file
called cdk.context.json
. You must commit this file to source control so
that the lookup values are available in non-privileged environments such
as CI build steps, and to ensure your template builds are repeatable.
Here's how Key.fromLookup()
can be used:
IKey myKeyLookup = Key.fromLookup(this, "MyKeyLookup", KeyLookupOptions.builder() .aliasName("alias/KeyAlias") .build()); Role role = Role.Builder.create(this, "MyRole") .assumedBy(new ServicePrincipal("lambda.amazonaws.com")) .build(); myKeyLookup.grantEncryptDecrypt(role);
Note that a call to .addToResourcePolicy(statement)
on myKeyLookup
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.
Controlling access and usage of KMS Keys requires the use of key policies (resource-based policies attached to the key); this is in contrast to most other AWS resources where access can be entirely controlled with IAM policies, and optionally complemented with resource policies. For more in-depth understanding of KMS key access and policies, see
KMS keys can be created to trust IAM policies. This is the default behavior for both the KMS APIs and in
the console. This behavior is enabled by the '@aws-cdk/aws-kms:defaultKeyPolicies' feature flag,
which is set for all new projects; for existing projects, this same behavior can be enabled by
passing the trustAccountIdentities
property as true
when creating the key:
Key.Builder.create(this, "MyKey").trustAccountIdentities(true).build();
With either the @aws-cdk/aws-kms:defaultKeyPolicies
feature flag set,
or the trustAccountIdentities
prop set, the Key will be given the following default key policy:
{ "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:root"}, "Action": "kms:*", "Resource": "*" }
This policy grants full access to the key to the root account user. This enables the root account user -- via IAM policies -- to grant access to other IAM principals. With the above default policy, future permissions can be added to either the key policy or IAM principal policy.
Key key = new Key(this, "MyKey"); User user = new User(this, "MyUser"); key.grantEncrypt(user);
Adopting the default KMS key policy (and so trusting account identities) solves many issues around cyclic dependencies between stacks. Without this default key policy, future permissions must be added to both the key policy and IAM principal policy, which can cause cyclic dependencies if the permissions cross stack boundaries. (For example, an encrypted bucket in one stack, and Lambda function that accesses it in another.)
The default key policy can be amended or replaced entirely, depending on your use case and requirements.
A common addition to the key policy would be to add other key admins that are allowed to administer the key
(e.g., change permissions, revoke, delete). Additional key admins can be specified at key creation or after
via the grantAdmin
method.
IRole myTrustedAdminRole = Role.fromRoleArn(this, "TrustedRole", "arn:aws:iam:...."); Key key = Key.Builder.create(this, "MyKey") .admins(List.of(myTrustedAdminRole)) .build(); Key secondKey = new Key(this, "MyKey2"); secondKey.grantAdmin(myTrustedAdminRole);
Alternatively, a custom key policy can be specified, which will replace the default key policy.
Note: In applications without the '@aws-cdk/aws-kms:defaultKeyPolicies' feature flag set and with
trustedAccountIdentities
set to false (the default), specifying a policy at key creation appends the provided policy to the default key policy, rather than replacing the default policy.
IRole myTrustedAdminRole = Role.fromRoleArn(this, "TrustedRole", "arn:aws:iam:...."); // Creates a limited admin policy and assigns to the account root. PolicyDocument myCustomPolicy = PolicyDocument.Builder.create() .statements(List.of(PolicyStatement.Builder.create() .actions(List.of("kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*")) .principals(List.of(new AccountRootPrincipal())) .resources(List.of("*")) .build())) .build(); Key key = Key.Builder.create(this, "MyKey") .policy(myCustomPolicy) .build();
Warning: Replacing the default key policy with one that only grants access to a specific user or role runs the risk of the key becoming unmanageable if that user or role is deleted. It is highly recommended that the key policy grants access to the account root, rather than specific principals. See https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html for more information.