532 lines
19 KiB
TypeScript
532 lines
19 KiB
TypeScript
import type { Construct } from 'constructs';
|
|
import { Alias } from './alias';
|
|
import { KeyGrants } from './key-grants';
|
|
import type { KeyLookupOptions } from './key-lookup';
|
|
import type { IKeyRef, KeyReference } from './kms.generated';
|
|
import { CfnKey } from './kms.generated';
|
|
import * as iam from '../../aws-iam';
|
|
import type { Duration, IResource, RemovalPolicy, ResourceProps } from '../../core';
|
|
import { Resource } from '../../core';
|
|
/**
|
|
* A KMS Key, either managed by this CDK app, or imported.
|
|
*
|
|
* This interface does double duty: it represents an actual KMS keys, but it
|
|
* also represents things that can behave like KMS keys, like a key alias.
|
|
*/
|
|
export interface IKey extends IResource, IKeyRef {
|
|
/**
|
|
* The ARN of the key.
|
|
*
|
|
* @attribute
|
|
*/
|
|
readonly keyArn: string;
|
|
/**
|
|
* The ID of the key
|
|
* (the part that looks something like: 1234abcd-12ab-34cd-56ef-1234567890ab).
|
|
*
|
|
* @attribute
|
|
*/
|
|
readonly keyId: string;
|
|
/**
|
|
* Defines a new alias for the key.
|
|
*/
|
|
addAlias(alias: string): Alias;
|
|
/**
|
|
* Adds a statement to the KMS key resource policy.
|
|
* @param statement The policy statement to add
|
|
* @param allowNoOp 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.
|
|
*/
|
|
addToResourcePolicy(statement: iam.PolicyStatement, allowNoOp?: boolean): iam.AddToResourcePolicyResult;
|
|
/**
|
|
* Grant the indicated permissions on this key to the given principal
|
|
*/
|
|
grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
|
|
/**
|
|
* Grant decryption permissions using this key to the given principal
|
|
*/
|
|
grantDecrypt(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant encryption permissions using this key to the given principal
|
|
*/
|
|
grantEncrypt(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant encryption and decryption permissions using this key to the given principal
|
|
*/
|
|
grantEncryptDecrypt(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant sign permissions using this key to the given principal
|
|
*/
|
|
grantSign(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant verify permissions using this key to the given principal
|
|
*/
|
|
grantVerify(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant sign and verify permissions using this key to the given principal
|
|
*/
|
|
grantSignVerify(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant permissions to generating MACs to the given principal
|
|
*/
|
|
grantGenerateMac(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant permissions to verifying MACs to the given principal
|
|
*/
|
|
grantVerifyMac(grantee: iam.IGrantable): iam.Grant;
|
|
}
|
|
declare abstract class KeyBase extends Resource implements IKey {
|
|
/**
|
|
* The ARN of the key.
|
|
*/
|
|
abstract readonly keyArn: string;
|
|
abstract readonly keyId: string;
|
|
/**
|
|
* Optional policy document that represents the resource policy of this key.
|
|
*
|
|
* If specified, addToResourcePolicy can be used to edit this policy.
|
|
* Otherwise this method will no-op.
|
|
*/
|
|
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. This matches the default behavior when creating
|
|
* KMS keys via the API or console.
|
|
*/
|
|
protected abstract readonly trustAccountIdentities: boolean;
|
|
/**
|
|
* Collection of aliases added to the key
|
|
*
|
|
* Tracked to determine whether or not the aliasName should be added to the end of its ID
|
|
*/
|
|
private readonly aliases;
|
|
constructor(scope: Construct, id: string, props?: ResourceProps);
|
|
get keyRef(): KeyReference;
|
|
/**
|
|
* Collection of grant methods for a Key
|
|
*/
|
|
get grants(): KeyGrants;
|
|
/**
|
|
* Defines a new alias for the key.
|
|
*/
|
|
addAlias(aliasName: string): Alias;
|
|
/**
|
|
* Adds a statement to the KMS key resource policy.
|
|
* @param statement The policy statement to add
|
|
* @param allowNoOp 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.
|
|
*/
|
|
addToResourcePolicy(statement: iam.PolicyStatement, allowNoOp?: boolean): iam.AddToResourcePolicyResult;
|
|
/**
|
|
* Grant the indicated permissions on this key to the given principal
|
|
*
|
|
* 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.
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
|
|
/**
|
|
* Grant decryption permissions using this key to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantDecrypt(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant encryption permissions using this key to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantEncrypt(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant encryption and decryption permissions using this key to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantEncryptDecrypt(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant sign permissions using this key to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantSign(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant verify permissions using this key to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantVerify(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant sign and verify permissions using this key to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantSignVerify(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant permissions to generating MACs to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantGenerateMac(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Grant permissions to verifying MACs to the given principal
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantVerifyMac(grantee: iam.IGrantable): iam.Grant;
|
|
}
|
|
/**
|
|
* The key spec, represents the cryptographic configuration of keys.
|
|
*/
|
|
export declare enum KeySpec {
|
|
/**
|
|
* The default key spec.
|
|
*
|
|
* Valid usage: ENCRYPT_DECRYPT
|
|
*/
|
|
SYMMETRIC_DEFAULT = "SYMMETRIC_DEFAULT",
|
|
/**
|
|
* RSA with 2048 bits of key.
|
|
*
|
|
* Valid usage: ENCRYPT_DECRYPT and SIGN_VERIFY
|
|
*/
|
|
RSA_2048 = "RSA_2048",
|
|
/**
|
|
* RSA with 3072 bits of key.
|
|
*
|
|
* Valid usage: ENCRYPT_DECRYPT and SIGN_VERIFY
|
|
*/
|
|
RSA_3072 = "RSA_3072",
|
|
/**
|
|
* RSA with 4096 bits of key.
|
|
*
|
|
* Valid usage: ENCRYPT_DECRYPT and SIGN_VERIFY
|
|
*/
|
|
RSA_4096 = "RSA_4096",
|
|
/**
|
|
* NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and
|
|
* SHA-256 for the message digest.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ECC_NIST_P256 = "ECC_NIST_P256",
|
|
/**
|
|
* NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and
|
|
* SHA-384 for the message digest.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ECC_NIST_P384 = "ECC_NIST_P384",
|
|
/**
|
|
* NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and
|
|
* SHA-512 for the message digest.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ECC_NIST_P521 = "ECC_NIST_P521",
|
|
/**
|
|
* Standards for Efficient Cryptography 2, Section 2.4.1, ECDSA signature on the Koblitz curve.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ECC_SECG_P256K1 = "ECC_SECG_P256K1",
|
|
/**
|
|
* Hash-Based Message Authentication Code as defined in RFC 2104 using the message digest function SHA224.
|
|
*
|
|
* Valid usage: GENERATE_VERIFY_MAC
|
|
*/
|
|
HMAC_224 = "HMAC_224",
|
|
/**
|
|
* Hash-Based Message Authentication Code as defined in RFC 2104 using the message digest function SHA256.
|
|
*
|
|
* Valid usage: GENERATE_VERIFY_MAC
|
|
*/
|
|
HMAC_256 = "HMAC_256",
|
|
/**
|
|
* Hash-Based Message Authentication Code as defined in RFC 2104 using the message digest function SHA384.
|
|
*
|
|
* Valid usage: GENERATE_VERIFY_MAC
|
|
*/
|
|
HMAC_384 = "HMAC_384",
|
|
/**
|
|
* Hash-Based Message Authentication Code as defined in RFC 2104 using the message digest function SHA512.
|
|
*
|
|
* Valid usage: GENERATE_VERIFY_MAC
|
|
*/
|
|
HMAC_512 = "HMAC_512",
|
|
/**
|
|
* Elliptic curve key spec available only in China Regions.
|
|
*
|
|
* Valid usage: ENCRYPT_DECRYPT and SIGN_VERIFY
|
|
*/
|
|
SM2 = "SM2",
|
|
/**
|
|
* ML-DSA-44 lattice-based digital signature algorithm.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ML_DSA_44 = "ML_DSA_44",
|
|
/**
|
|
* ML-DSA-65 lattice-based digital signature algorithm.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ML_DSA_65 = "ML_DSA_65",
|
|
/**
|
|
* ML-DSA-87 lattice-based digital signature algorithm.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ML_DSA_87 = "ML_DSA_87",
|
|
/**
|
|
* NIST-standard Edwards25519 (ed25519) elliptic curve key pair.
|
|
*
|
|
* Valid usage: SIGN_VERIFY
|
|
*/
|
|
ECC_NIST_EDWARDS25519 = "ECC_NIST_EDWARDS25519"
|
|
}
|
|
/**
|
|
* The key usage, represents the cryptographic operations of keys.
|
|
*/
|
|
export declare enum KeyUsage {
|
|
/**
|
|
* Encryption and decryption.
|
|
*/
|
|
ENCRYPT_DECRYPT = "ENCRYPT_DECRYPT",
|
|
/**
|
|
* Signing and verification
|
|
*/
|
|
SIGN_VERIFY = "SIGN_VERIFY",
|
|
/**
|
|
* Generating and verifying MACs
|
|
*/
|
|
GENERATE_VERIFY_MAC = "GENERATE_VERIFY_MAC",
|
|
/**
|
|
* Deriving shared secrets
|
|
*/
|
|
KEY_AGREEMENT = "KEY_AGREEMENT"
|
|
}
|
|
/**
|
|
* Construction properties for a KMS Key object
|
|
*/
|
|
export interface KeyProps {
|
|
/**
|
|
* A description of the key. Use a description that helps your users decide
|
|
* whether the key is appropriate for a particular task.
|
|
*
|
|
* @default - No description.
|
|
*/
|
|
readonly description?: string;
|
|
/**
|
|
* Initial alias to add to the key
|
|
*
|
|
* More aliases can be added later by calling `addAlias`.
|
|
*
|
|
* @default - No alias is added for the key.
|
|
*/
|
|
readonly alias?: string;
|
|
/**
|
|
* Indicates whether AWS KMS rotates the key.
|
|
*
|
|
* @default false
|
|
*/
|
|
readonly enableKeyRotation?: boolean;
|
|
/**
|
|
* The period between each automatic rotation.
|
|
*
|
|
* @default - set by CFN to 365 days.
|
|
*/
|
|
readonly rotationPeriod?: Duration;
|
|
/**
|
|
* Indicates whether the key is available for use.
|
|
*
|
|
* @default - Key is enabled.
|
|
*/
|
|
readonly enabled?: boolean;
|
|
/**
|
|
* The cryptographic configuration of the key. The valid value depends on usage of the key.
|
|
*
|
|
* IMPORTANT: If you change this property of an existing key, the existing key is scheduled for deletion
|
|
* and a new key is created with the specified value.
|
|
*
|
|
* @default KeySpec.SYMMETRIC_DEFAULT
|
|
*/
|
|
readonly keySpec?: KeySpec;
|
|
/**
|
|
* The cryptographic operations for which the key can be used.
|
|
*
|
|
* IMPORTANT: If you change this property of an existing key, the existing key is scheduled for deletion
|
|
* and a new key is created with the specified value.
|
|
*
|
|
* @default KeyUsage.ENCRYPT_DECRYPT
|
|
*/
|
|
readonly keyUsage?: KeyUsage;
|
|
/**
|
|
* Creates a multi-Region primary key that you can replicate in other AWS Regions.
|
|
*
|
|
* You can't change the `multiRegion` value after the KMS key is created.
|
|
*
|
|
* IMPORTANT: If you change the value of the `multiRegion` property on an existing KMS key, the update request fails,
|
|
* regardless of the value of the UpdateReplacePolicy attribute.
|
|
* This prevents you from accidentally deleting a KMS key by changing an immutable property value.
|
|
*
|
|
* @default false
|
|
* @see https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html
|
|
*/
|
|
readonly multiRegion?: boolean;
|
|
/**
|
|
* Custom policy document to attach to the KMS key.
|
|
*
|
|
* NOTE - If the `@aws-cdk/aws-kms:defaultKeyPolicies` feature flag is set (the default for new projects),
|
|
* this policy will *override* the default key policy and become the only key policy for the key. If the
|
|
* feature flag is not set, this policy will be appended to the default key policy.
|
|
*
|
|
* @default - A policy document with permissions for the account root to
|
|
* administer the key will be created.
|
|
*/
|
|
readonly policy?: iam.PolicyDocument;
|
|
/**
|
|
* A list of principals to add as key administrators to the key policy.
|
|
*
|
|
* 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).
|
|
*
|
|
* These principals will be added to the default key policy (if none specified), or to the specified policy (if provided).
|
|
*
|
|
* @default []
|
|
*/
|
|
readonly admins?: iam.IPrincipal[];
|
|
/**
|
|
* Whether the encryption key should be retained when it is removed from the Stack. This is useful when one wants to
|
|
* retain access to data that was encrypted with a key that is being retired.
|
|
*
|
|
* @default RemovalPolicy.Retain
|
|
*/
|
|
readonly removalPolicy?: RemovalPolicy;
|
|
/**
|
|
* Specifies the number of days in the waiting period before
|
|
* AWS KMS deletes a CMK that has been removed from a CloudFormation stack.
|
|
*
|
|
* When you remove a customer master key (CMK) from a CloudFormation stack, AWS KMS schedules the CMK for deletion
|
|
* and starts the mandatory waiting period. The PendingWindowInDays property determines the length of waiting period.
|
|
* During the waiting period, the key state of CMK is Pending Deletion, which prevents the CMK from being used in
|
|
* cryptographic operations. When the waiting period expires, AWS KMS permanently deletes the CMK.
|
|
*
|
|
* Enter a value between 7 and 30 days.
|
|
*
|
|
* @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-key.html#cfn-kms-key-pendingwindowindays
|
|
* @default - 30 days
|
|
*/
|
|
readonly pendingWindow?: Duration;
|
|
}
|
|
/**
|
|
* Defines a KMS key.
|
|
*
|
|
* @resource AWS::KMS::Key
|
|
*/
|
|
export declare class Key extends KeyBase {
|
|
/**
|
|
* Uniquely identifies this class.
|
|
*/
|
|
static readonly PROPERTY_INJECTION_ID: string;
|
|
/**
|
|
* The default key id of the dummy key.
|
|
*
|
|
* This value is used as a dummy key id if the key was not found
|
|
* by the `Key.fromLookup()` method.
|
|
*/
|
|
static readonly DEFAULT_DUMMY_KEY_ID = "1234abcd-12ab-34cd-56ef-1234567890ab";
|
|
/**
|
|
* Import an externally defined KMS Key using its ARN.
|
|
*
|
|
* @param scope the construct that will "own" the imported key.
|
|
* @param id the id of the imported key in the construct tree.
|
|
* @param keyArn the ARN of an existing KMS key.
|
|
*/
|
|
static fromKeyArn(scope: Construct, id: string, keyArn: string): IKey;
|
|
/**
|
|
* Create a mutable `IKey` based on a low-level `CfnKey`.
|
|
* 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.
|
|
*/
|
|
static fromCfnKey(cfnKey: CfnKey): IKey;
|
|
/**
|
|
* Import an existing Key by querying the AWS environment this stack is deployed to.
|
|
*
|
|
* 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.
|
|
*/
|
|
static fromLookup(scope: Construct, id: string, options: KeyLookupOptions): IKey;
|
|
/**
|
|
* Checks if the key returned by the `Key.fromLookup()` method is a dummy key,
|
|
* i.e., a key that was not found.
|
|
*
|
|
* This method can only be used if the `returnDummyKeyOnMissing` option
|
|
* is set to `true` in the `options` for the `Key.fromLookup()` method.
|
|
*/
|
|
static isLookupDummy(key: IKeyRef): boolean;
|
|
readonly keyArn: string;
|
|
readonly keyId: string;
|
|
protected readonly policy?: iam.PolicyDocument;
|
|
protected readonly trustAccountIdentities: boolean;
|
|
private readonly enableKeyRotation?;
|
|
constructor(scope: Construct, id: string, props?: KeyProps);
|
|
/**
|
|
* Grant admins permissions using this key to the given principal
|
|
*
|
|
* 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).
|
|
*
|
|
* [disable-awslint:no-grants]
|
|
*/
|
|
grantAdmin(grantee: iam.IGrantable): iam.Grant;
|
|
/**
|
|
* Adds the default key policy to the key. This policy gives the AWS account (root user) full access to the CMK,
|
|
* which reduces the risk of the CMK becoming unmanageable and enables IAM policies to allow access to the CMK.
|
|
* This is the same policy that is default when creating a Key via the KMS API or Console.
|
|
* @see https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default
|
|
*/
|
|
private addDefaultAdminPolicy;
|
|
/**
|
|
* Grants the account admin privileges -- not full account access -- plus the GenerateDataKey action.
|
|
* The GenerateDataKey action was added for interop with S3 in https://github.com/aws/aws-cdk/issues/3458.
|
|
*
|
|
* This policy is discouraged and deprecated by the `@aws-cdk/aws-kms:defaultKeyPolicies` feature flag.
|
|
*
|
|
* @link https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default
|
|
* @deprecated
|
|
*/
|
|
private addLegacyAdminPolicy;
|
|
}
|
|
export {};
|