Class Key

Key(Construct, string, IKeyProps?)

IResource

IKeyRef

IConstruct

IDependable

IEnvironmentAware

Inherited Members

Resource.IsOwnedResource(IConstruct)

Resource.IsResource(IConstruct)

Resource.ApplyRemovalPolicy(RemovalPolicy)

Resource.GeneratePhysicalName()

Resource.GetResourceArnAttribute(string, IArnComponents)

Resource.GetResourceNameAttribute(string)

Resource.Env

Resource.PhysicalName

Resource.Stack

Namespace: Amazon.CDK.AWS.KMS

Assembly: Amazon.CDK.Lib.dll

Syntax (csharp)

public class Key : Resource, IKey, IResource, IKeyRef, IConstruct, IDependable, IEnvironmentAware

Syntax (vb)

Public Class Key Inherits Resource Implements IKey, IResource, IKeyRef, IConstruct, IDependable, IEnvironmentAware

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

Examples

using Amazon.CDK.AWS.KMS;


             var myKmsKey = new Key(this, "myKMSKey");
             var myBucket = new Bucket(this, "mySSEKMSEncryptedBucket", new BucketProps {
                 Encryption = BucketEncryption.KMS,
                 EncryptionKey = myKmsKey,
                 ObjectOwnership = ObjectOwnership.BUCKET_OWNER_ENFORCED
             });
             new Distribution(this, "myDist", new DistributionProps {
                 DefaultBehavior = new BehaviorOptions {
                     Origin = S3BucketOrigin.WithOriginAccessControl(myBucket)
                 }
             });

Synopsis

Constructors

Defines a KMS key.

Properties

DEFAULT_DUMMY_KEY_ID	The default key id of the dummy key.
KeyArn	The ARN of the key.
KeyId	The ID of the key (the part that looks something like: 1234abcd-12ab-34cd-56ef-1234567890ab).
KeyRef	A reference to a Key resource.
PROPERTY_INJECTION_ID	Uniquely identifies this class.
Policy	Optional policy document that represents the resource policy of this key.
TrustAccountIdentities	Optional property to control trusting account identities.

Methods

AddAlias(string)	Defines a new alias for the key.
AddToResourcePolicy(PolicyStatement, bool?)	Adds a statement to the KMS key resource policy.
FromCfnKey(CfnKey)	Create a mutable `IKey` based on a low-level `CfnKey`.
FromKeyArn(Construct, string, string)	Import an externally defined KMS Key using its ARN.
FromLookup(Construct, string, IKeyLookupOptions)	Import an existing Key by querying the AWS environment this stack is deployed to.
Grant(IGrantable, params string[])	Grant the indicated permissions on this key to the given principal.
GrantAdmin(IGrantable)	Grant admins permissions using this key to the given principal.
GrantDecrypt(IGrantable)	Grant decryption permissions using this key to the given principal.
GrantEncrypt(IGrantable)	Grant encryption permissions using this key to the given principal.
GrantEncryptDecrypt(IGrantable)	Grant encryption and decryption permissions using this key to the given principal.
GrantGenerateMac(IGrantable)	Grant permissions to generating MACs to the given principal.
GrantSign(IGrantable)	Grant sign permissions using this key to the given principal.
GrantSignVerify(IGrantable)	Grant sign and verify permissions using this key to the given principal.
GrantVerify(IGrantable)	Grant verify permissions using this key to the given principal.
GrantVerifyMac(IGrantable)	Grant permissions to verifying MACs to the given principal.
IsLookupDummy(IKeyRef)	Checks if the key returned by the `Key.fromLookup()` method is a dummy key, i.e., a key that was not found.

Constructors

Key(Construct, string, IKeyProps?)

Defines a KMS key.

public Key(Construct scope, string id, IKeyProps? props = null)

Parameters

scope Construct
id string
props IKeyProps

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

Examples

using Amazon.CDK.AWS.KMS;


             var myKmsKey = new Key(this, "myKMSKey");
             var myBucket = new Bucket(this, "mySSEKMSEncryptedBucket", new BucketProps {
                 Encryption = BucketEncryption.KMS,
                 EncryptionKey = myKmsKey,
                 ObjectOwnership = ObjectOwnership.BUCKET_OWNER_ENFORCED
             });
             new Distribution(this, "myDist", new DistributionProps {
                 DefaultBehavior = new BehaviorOptions {
                     Origin = S3BucketOrigin.WithOriginAccessControl(myBucket)
                 }
             });

Properties

DEFAULT_DUMMY_KEY_ID

The default key id of the dummy key.

public static string DEFAULT_DUMMY_KEY_ID { get; }

Property Value

Remarks

This value is used as a dummy key id if the key was not found by the Key.fromLookup() method.

KeyArn

The ARN of the key.

public virtual string KeyArn { get; }

Property Value

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

KeyId

The ID of the key (the part that looks something like: 1234abcd-12ab-34cd-56ef-1234567890ab).

public virtual string KeyId { get; }

Property Value

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

KeyRef

A reference to a Key resource.

public virtual IKeyReference KeyRef { get; }

Property Value

IKeyReference

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

PROPERTY_INJECTION_ID

Uniquely identifies this class.

public static string PROPERTY_INJECTION_ID { get; }

Property Value

IAddToResourcePolicyResult

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

Policy

Optional policy document that represents the resource policy of this key.

protected virtual PolicyDocument? Policy { get; }

Property Value

PolicyDocument

Remarks

If specified, addToResourcePolicy can be used to edit this policy. Otherwise this method will no-op.

TrustAccountIdentities

Optional property to control trusting account identities.

protected virtual bool TrustAccountIdentities { get; }

Property Value

bool

Remarks

If specified, grants will default identity policies instead of to both resource and identity policies. This matches the default behavior when creating KMS keys via the API or console.

Methods

AddAlias(string)

Defines a new alias for the key.

public virtual Alias AddAlias(string aliasName)

Parameters

aliasName string

Returns

Alias

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

AddToResourcePolicy(PolicyStatement, bool?)

Adds a statement to the KMS key resource policy.

public virtual IAddToResourcePolicyResult AddToResourcePolicy(PolicyStatement statement, bool? allowNoOp = null)

Parameters

statement PolicyStatement: The policy statement to add.
allowNoOp bool?: If this is set to false and there is no policy defined (i.e. external key), the operation will fail. Otherwise, it will no-op.

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

FromCfnKey(CfnKey)

Create a mutable IKey based on a low-level CfnKey.

public static IKey FromCfnKey(CfnKey cfnKey)

Parameters

cfnKey CfnKey

Returns

Remarks

This is most useful when combined with the cloudformation-include module. This method is different than fromKeyArn() because the IKey returned from this method is mutable; meaning, calling any mutating methods on it, like IKey.addToResourcePolicy(), will actually be reflected in the resulting template, as opposed to the object returned from fromKeyArn(), on which calling those methods would have no effect.

FromKeyArn(Construct, string, string)

Import an externally defined KMS Key using its ARN.

public static IKey FromKeyArn(Construct scope, string id, string keyArn)

Parameters

scope Construct: the construct that will "own" the imported key.
id string: the id of the imported key in the construct tree.
keyArn string: the ARN of an existing KMS key.

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

FromLookup(Construct, string, IKeyLookupOptions)

Import an existing Key by querying the AWS environment this stack is deployed to.

public static IKey FromLookup(Construct scope, string id, IKeyLookupOptions options)

Parameters

scope Construct
id string
options IKeyLookupOptions

Returns

Remarks

This function only needs to be used to use Keys not defined in your CDK application. If you are looking to share a Key between stacks, you can pass the Key object between stacks and use it as normal. In addition, it's not necessary to use this method if an interface accepts an IKey. In this case, Alias.fromAliasName() can be used which returns an alias that extends IKey.

Calling this method will lead to a lookup when the CDK CLI is executed. You can therefore not use any values that will only be available at CloudFormation execution time (i.e., Tokens).

If you set returnDummyKeyOnMissing to true in options and the key was not found, this method will return a dummy key with a key id '1234abcd-12ab-34cd-56ef-1234567890ab'. The value of the dummy key id can also be referenced using the Key.DEFAULT_DUMMY_KEY_ID variable, and you can check if the key is a dummy key by using the Key.isLookupDummy() method.

The Key information will be cached in cdk.context.json and the same Key will be used on future runs. To refresh the lookup, you will have to evict the value from the cache using the cdk context command. See https://docs.aws.amazon.com/cdk/latest/guide/context.html for more information.

Grant(IGrantable, params string[])

Grant the indicated permissions on this key to the given principal.

public virtual Grant Grant(IGrantable grantee, params string[] actions)

Parameters

grantee IGrantable
actions string[]

Returns

Remarks

This modifies both the principal's policy as well as the resource policy, since the default CloudFormation setup for KMS keys is that the policy must not be empty and so default grants won't work.

GrantAdmin(IGrantable)

Grant admins permissions using this key to the given principal.

public virtual Grant GrantAdmin(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Key administrators have permissions to manage the key (e.g., change permissions, revoke), but do not have permissions to use the key in cryptographic operations (e.g., encrypt, decrypt).

GrantDecrypt(IGrantable)

Grant decryption permissions using this key to the given principal.

public virtual Grant GrantDecrypt(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantEncrypt(IGrantable)

Grant encryption permissions using this key to the given principal.

public virtual Grant GrantEncrypt(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantEncryptDecrypt(IGrantable)

Grant encryption and decryption permissions using this key to the given principal.

public virtual Grant GrantEncryptDecrypt(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantGenerateMac(IGrantable)

Grant permissions to generating MACs to the given principal.

public virtual Grant GrantGenerateMac(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantSign(IGrantable)

Grant sign permissions using this key to the given principal.

public virtual Grant GrantSign(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantSignVerify(IGrantable)

Grant sign and verify permissions using this key to the given principal.

public virtual Grant GrantSignVerify(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantVerify(IGrantable)

Grant verify permissions using this key to the given principal.

public virtual Grant GrantVerify(IGrantable grantee)

Parameters

grantee IGrantable

Returns

Remarks

Resource: AWS::KMS::Key

ExampleMetadata: infused

GrantVerifyMac(IGrantable)

Grant permissions to verifying MACs to the given principal.

public virtual Grant GrantVerifyMac(IGrantable grantee)

Parameters

grantee IGrantable

Returns