Skip to main content

CDK EC2 Key Pair

CDK EC2 Key Pair

Source Test Construct Hub codecov Maintainability GitHub

npm PyPI Maven Central NuGet Go

Downloads npm PyPI NuGet

AWS CDK L3 construct for managing EC2 Key Pairs.

Manages RSA and ED25519 Key Pairs in EC2 through a Lambda function.

Support for public key format in:

  • OpenSSH
  • ssh
  • PEM
  • PKCS#1
  • PKCS#8
  • RFC4253 (Base64 encoded)
  • PuTTY ppk

Installation

The construct is available for TypeScript/JavaScript, Python, Java, C#/.NET and Go:

Language Package
TypeScript / JavaScript npm
Python PyPI
Java Maven Central
C# / .NET NuGet
Go Go
# TypeScript / JavaScript
npm install cdk-ec2-key-pair

# Python
pip install cdk-ec2-key-pair

# Java (Maven), with the version of the release
#   com.udondan:cdk-ec2-key-pair

# C# / .NET
dotnet add package CDK.EC2.KeyPair

# Go
go get udondan.github.io/cdk-ec2-key-pair/go/cdkec2keypair/v5

The package has peer dependencies, which need to be installed along with it:

  • aws-cdk-lib (^2.224.0)
  • constructs (^10.0.0)

Usage

import cdk = require('aws-cdk-lib');
import { Construct } from 'constructs';
import { KeyPair } from 'cdk-ec2-key-pair';

// ...

// Create the Key Pair
const key = new KeyPair(this, 'A-Key-Pair', {
  keyPairName: 'a-key-pair',
  description: 'This is a Key Pair',
  storePublicKey: true, // by default the public key will not be stored in Secrets Manager
});

// Grant read access to the private key secret
key.privateKeySecret.grantRead(someRole);

// Grant read access to the public key secret (if stored)
key.publicKeySecret?.grantRead(anotherRole);

// Access the secret ARN
const privateKeyArn = key.privateKeySecret.secretArn;

// Use Key Pair on an EC2 instance
new ec2.Instance(this, 'An-Instance', {
  keyPair: key,
  // ...
});

The private (and optionally the public) key will be stored in AWS Secrets Manager. The secret names by default are prefixed with ec2-ssh-key/. The private key is suffixed with /private, the public key is suffixed with /public. So in this example they will be stored as ec2-ssh-key/a-key-pair/private and ec2-ssh-key/a-key-pair/public.

Accessing Secrets

The construct exposes the secrets as ISecret objects:

// Access the private key secret
const privateKeySecret = key.privateKeySecret;

// Access the public key secret (if storePublicKey was enabled)
const publicKeySecret = key.publicKeySecret;

// Get the secret ARN
const secretArn = key.privateKeySecret.secretArn;

// Use the secret value in CloudFormation (e.g., for custom resources)
const secretValue = key.privateKeySecret.secretValue;

To download the private key via AWS CLI you can run:

aws secretsmanager get-secret-value \
  --secret-id ec2-ssh-key/a-key-pair/private \
  --query SecretString \
  --output text

Tag support

The construct supports tagging:

cdk.Tags.of(key).add('someTag', 'some value');

We also use tags to restrict update/delete actions to those, the construct created itself. The Lambda function, which backs the custom CFN resource, is not able to manipulate other keys/secrets. The tag we use for identifying these resources is CreatedByCfnCustomResource with value CFN::Resource::Custom::EC2-Key-Pair.

Updates

Since an EC2 KeyPair cannot be updated, you cannot change any property related to the KeyPair. The code has checks in place which will prevent any attempt to do so. If you try, the stack will end in a failed state. In that case you can safely continue the rollback in the AWS console and ignore the key resource.

You can, however, change properties that only relate to the secrets. These are the KMS keys used for encryption, the secretPrefix, description and removeKeySecretsAfterDays.

Customizing the Lambda runtime

The backing Lambda function defaults to the NODEJS_24_X runtime. If you need to pin to a specific Node.js version, pass the lambdaRuntime property:

import { Runtime } from 'aws-cdk-lib/aws-lambda';

const keyPair = new KeyPair(this, 'A-Key-Pair', {
  keyPairName: 'a-key-pair',
  lambdaRuntime: Runtime.NODEJS_22_X,
});

Note: The Lambda function is shared across all KeyPair instances in the same stack. Only the value set on the first instance takes effect.

Encryption

Secrets in the AWS Secrets Manager by default are encrypted with the key alias/aws/secretsmanager.

To use a custom KMS key you can pass it to the Key Pair:

const kmsKey = new kms.Key(this, 'KMS-key');

const keyPair = new KeyPair(this, 'A-Key-Pair', {
  keyPairName: 'a-key-pair',
  kms: kmsKey,
});

This KMS key needs to be created in the same stack. You cannot use a key imported via ARN, because the keys access policy will need to be modified.

To use different KMS keys for the private and public key, use the kmsPrivateKey and kmsPublicKey instead:

const kmsKeyPrivate = new kms.Key(this, 'KMS-key-private');
const kmsKeyPublic = new kms.Key(this, 'KMS-key-public');

const keyPair = new KeyPair(this, 'A-Key-Pair', {
  keyPairName: 'a-key-pair',
  kmsPrivateKey: kmsKeyPrivate,
  kmsPublicKey: kmsKeyPublic,
});

Importing public key

You can create a key pair by importing the public key. Obviously, in this case the private key won't be available in secrets manager.

The public key has to be in OpenSSH format.

new KeyPair(this, 'Test-Key-Pair', {
  keyPairName: 'imported-key-pair',
  publicKey: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCuMmbK...',
});

Using the key pair for CloudFront signed url/cookies

You can use this library for generating keys for CloudFront signed url/cookies.

Make sure to set publicKeyFormat to PublicKeyFormat.PEM as that is the format required for CloudFront. You also have to set exposePublicKey to true so you can actually get the public key.

const key = new KeyPair(this, 'Signing-Key-Pair', {
  keyPairName: 'CFN-signing-key',
  exposePublicKey: true,
  storePublicKey: true,
  publicKeyFormat: PublicKeyFormat.PEM,
});

const pubKey = new cloudfront.PublicKey(this, 'Signing-Public-Key', {
  encodedKey: key.publicKeyValue,
});
const trustedKeyGroupForCF = new cloudfront.KeyGroup(
  this,
  'Signing-Key-Group',
  {
    items: [pubKey],
  },
);

Metadata

Release files for cdk-ec2-key-pair 5.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cdk-ec2-key-pair 5.2.0
File Size Uploaded Provenance Actions
cdk_ec2_key_pair-5.2.0.tar.gz 312.3 kB With provenance Details for cdk_ec2_key_pair-5.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cdk-ec2-key-pair 5.2.0
File Interpreter ABI Platform Actions
cdk_ec2_key_pair-5.2.0-py3-none-any.whl Python 3 none any Details for cdk_ec2_key_pair-5.2.0-py3-none-any.whl

Total release size: 622.1 kB

Release files / cdk_ec2_key_pair-5.2.0.tar.gz

Download URL cdk_ec2_key_pair-5.2.0.tar.gz
Size 312.3 kB
Tags Source
SHA-256 checksum
How to use checksums
918fa1782d99e68e1ab447cb16fbe103951e2010d4c8d98fe532e9f6487880ee
BLAKE2b-256 checksum
How to use checksums
84937332a43526fbca706d3b8486671c3d0ea03c5e71e95ee1e7f194efc32725
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / cdk_ec2_key_pair-5.2.0-py3-none-any.whl

Download URL cdk_ec2_key_pair-5.2.0-py3-none-any.whl
Size 309.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c731a5d87f4b33c03d196d6bace48863697967f3b193ca1753e5974e57ac5b58
BLAKE2b-256 checksum
How to use checksums
dda30f5671545e6f5ae7ff82bcd691426f247941092a057b04135cf7075f4757
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for cdk-ec2-key-pair 5.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cdk_ec2_key_pair-5.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

5.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page