# CDK EC2 Key Pair
[](https://github.com/udondan/cdk-ec2-key-pair)
[](https://github.com/udondan/cdk-ec2-key-pair/actions?query=workflow%3ATest)
[](https://github.com/udondan/cdk-ec2-key-pair/blob/main/LICENSE)
[](https://constructs.dev/packages/cdk-ec2-key-pair)
[](https://www.npmjs.com/package/cdk-ec2-key-pair)
[](https://pypi.org/project/cdk-ec2-key-pair/)
[](https://www.npmjs.com/package/cdk-ec2-key-pair)
[](https://pypi.org/project/cdk-ec2-key-pair/)
[AWS CDK](https://aws.amazon.com/cdk/) L3 construct for managing [EC2 Key Pairs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html).
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
> [!NOTE]
> Please be aware, CloudFormation now natively supports creating EC2 Key Pairs via [AWS::EC2::KeyPair](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-keypair.html), so you can generally use [CDK's own KeyPair construct](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.KeyPair.html). There are a few differences, though, and this is why the custom construct remains valuable:
>
> * Instead of SSM Parameter Store, keys are stored in [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)
> * Secrets can be **KMS encrypted** - even different KMS keys for the private and public keys. Of course, SSM parameters *can* be encrypted too, CloudFormation just doesn't do it
> * Optionally, this construct can store and expose the public key, enabling the user to directly use it as input for other resources, e.g. for CloudFront signed urls
## Installation
This package has peer dependencies, which need to be installed along in the expected version.
For TypeScript/NodeJS, add these to your `dependencies` in `package.json`. For Python, add these to your `requirements.txt`:
* cdk-ec2-key-pair
* aws-cdk-lib (^2.116.0)
* constructs (^10.0.0)
## Usage
```python
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 to a role or user
key.grantReadOnPrivateKey(someRole);
// Grant read access to the public key to another role or user
key.grantReadOnPublicKey(anotherRole);
// 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`.
To download the private key via AWS cli you can run:
```bash
aws secretsmanager get-secret-value \
--secret-id ec2-ssh-key/a-key-pair/private \
--query SecretString \
--output text
```
### Tag support
The construct supports tagging:
```python
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`.
### 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:
```python
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:
```python
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.
```python
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.
```python
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],
},
);
```
Raw data
{
"_id": null,
"home_page": "https://github.com/udondan/cdk-ec2-key-pair",
"name": "cdk-ec2-key-pair",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Daniel Schroeder",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e9/e9/eb325605de84a642ec7da0a1cc52d95c478d1fd482ffdca309f62e7d375d/cdk-ec2-key-pair-4.0.0.tar.gz",
"platform": null,
"description": "# CDK EC2 Key Pair\n\n[](https://github.com/udondan/cdk-ec2-key-pair)\n[](https://github.com/udondan/cdk-ec2-key-pair/actions?query=workflow%3ATest)\n[](https://github.com/udondan/cdk-ec2-key-pair/blob/main/LICENSE)\n[](https://constructs.dev/packages/cdk-ec2-key-pair)\n\n[](https://www.npmjs.com/package/cdk-ec2-key-pair)\n[](https://pypi.org/project/cdk-ec2-key-pair/)\n\n\n[](https://www.npmjs.com/package/cdk-ec2-key-pair)\n[](https://pypi.org/project/cdk-ec2-key-pair/)\n\n[AWS CDK](https://aws.amazon.com/cdk/) L3 construct for managing [EC2 Key Pairs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html).\n\nManages RSA and ED25519 Key Pairs in EC2 through a Lambda function.\n\nSupport for public key format in:\n\n* OpenSSH\n* ssh\n* PEM\n* PKCS#1\n* PKCS#8\n* RFC4253 (Base64 encoded)\n* PuTTY ppk\n\n> [!NOTE]\n> Please be aware, CloudFormation now natively supports creating EC2 Key Pairs via [AWS::EC2::KeyPair](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-keypair.html), so you can generally use [CDK's own KeyPair construct](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.KeyPair.html). There are a few differences, though, and this is why the custom construct remains valuable:\n>\n> * Instead of SSM Parameter Store, keys are stored in [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)\n> * Secrets can be **KMS encrypted** - even different KMS keys for the private and public keys. Of course, SSM parameters *can* be encrypted too, CloudFormation just doesn't do it\n> * Optionally, this construct can store and expose the public key, enabling the user to directly use it as input for other resources, e.g. for CloudFront signed urls\n\n## Installation\n\nThis package has peer dependencies, which need to be installed along in the expected version.\n\nFor TypeScript/NodeJS, add these to your `dependencies` in `package.json`. For Python, add these to your `requirements.txt`:\n\n* cdk-ec2-key-pair\n* aws-cdk-lib (^2.116.0)\n* constructs (^10.0.0)\n\n## Usage\n\n```python\nimport cdk = require('aws-cdk-lib');\nimport { Construct } from 'constructs';\nimport { KeyPair } from 'cdk-ec2-key-pair';\n\n// ...\n\n// Create the Key Pair\nconst key = new KeyPair(this, 'A-Key-Pair', {\n keyPairName: 'a-key-pair',\n description: 'This is a Key Pair',\n storePublicKey: true, // by default the public key will not be stored in Secrets Manager\n});\n\n// Grant read access to the private key to a role or user\nkey.grantReadOnPrivateKey(someRole);\n\n// Grant read access to the public key to another role or user\nkey.grantReadOnPublicKey(anotherRole);\n\n// Use Key Pair on an EC2 instance\nnew ec2.Instance(this, 'An-Instance', {\n keyPair: key,\n // ...\n});\n```\n\nThe 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`.\n\nTo download the private key via AWS cli you can run:\n\n```bash\naws secretsmanager get-secret-value \\\n --secret-id ec2-ssh-key/a-key-pair/private \\\n --query SecretString \\\n --output text\n```\n\n### Tag support\n\nThe construct supports tagging:\n\n```python\ncdk.Tags.of(key).add('someTag', 'some value');\n```\n\nWe 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`.\n\n### Updates\n\nSince 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.\n\nYou can, however, change properties that only relate to the secrets. These are the KMS keys used for encryption, the `secretPrefix`, `description` and `removeKeySecretsAfterDays`.\n\n### Encryption\n\nSecrets in the AWS Secrets Manager by default are encrypted with the key `alias/aws/secretsmanager`.\n\nTo use a custom KMS key you can pass it to the Key Pair:\n\n```python\nconst kmsKey = new kms.Key(this, 'KMS-key');\n\nconst keyPair = new KeyPair(this, 'A-Key-Pair', {\n keyPairName: 'a-key-pair',\n kms: kmsKey,\n});\n```\n\nThis 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.\n\nTo use different KMS keys for the private and public key, use the `kmsPrivateKey` and `kmsPublicKey` instead:\n\n```python\nconst kmsKeyPrivate = new kms.Key(this, 'KMS-key-private');\nconst kmsKeyPublic = new kms.Key(this, 'KMS-key-public');\n\nconst keyPair = new KeyPair(this, 'A-Key-Pair', {\n keyPairName: 'a-key-pair',\n kmsPrivateKey: kmsKeyPrivate,\n kmsPublicKey: kmsKeyPublic,\n});\n```\n\n### Importing public key\n\nYou can create a key pair by importing the public key. Obviously, in this case the private key won't be available in secrets manager.\n\nThe public key has to be in OpenSSH format.\n\n```python\nnew KeyPair(this, 'Test-Key-Pair', {\n keyPairName: 'imported-key-pair',\n publicKey: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCuMmbK...',\n});\n```\n\n### Using the key pair for CloudFront signed url/cookies\n\nYou can use this library for generating keys for CloudFront signed url/cookies.\n\nMake sure to set `publicKeyFormat` to `PublicKeyFormat.PEM` as that is the format required for CloudFront.\nYou also have to set `exposePublicKey` to `true` so you can actually get the public key.\n\n```python\nconst key = new KeyPair(this, 'Signing-Key-Pair', {\n keyPairName: 'CFN-signing-key',\n exposePublicKey: true,\n storePublicKey: true,\n publicKeyFormat: PublicKeyFormat.PEM,\n});\n\nconst pubKey = new cloudfront.PublicKey(this, 'Signing-Public-Key', {\n encodedKey: key.publicKeyValue,\n});\nconst trustedKeyGroupForCF = new cloudfront.KeyGroup(\n this,\n 'Signing-Key-Group',\n {\n items: [pubKey],\n },\n);\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "CDK Construct for managing EC2 key pairs",
"version": "4.0.0",
"project_urls": {
"Homepage": "https://github.com/udondan/cdk-ec2-key-pair",
"Source": "https://github.com/udondan/cdk-ec2-key-pair.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "674d4d236f06deb6e4128c7d469e2b7647f1ee7d3134e439e9286d79a8c715c2",
"md5": "cb13b2b570ed8a81e91cac708cf7b4a5",
"sha256": "d9218fbf927d1127568337abb7fa9c9962254e77881625b5acc294581d903851"
},
"downloads": -1,
"filename": "cdk_ec2_key_pair-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cb13b2b570ed8a81e91cac708cf7b4a5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 51501,
"upload_time": "2024-03-23T14:58:14",
"upload_time_iso_8601": "2024-03-23T14:58:14.370419Z",
"url": "https://files.pythonhosted.org/packages/67/4d/4d236f06deb6e4128c7d469e2b7647f1ee7d3134e439e9286d79a8c715c2/cdk_ec2_key_pair-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9e9eb325605de84a642ec7da0a1cc52d95c478d1fd482ffdca309f62e7d375d",
"md5": "168357cefc421048b708df3bb8bb5b17",
"sha256": "73ec69109c4b84c577f6e5081fe0851e81af56315c9d35f20baf60eb37b56e18"
},
"downloads": -1,
"filename": "cdk-ec2-key-pair-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "168357cefc421048b708df3bb8bb5b17",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 53835,
"upload_time": "2024-03-23T14:58:15",
"upload_time_iso_8601": "2024-03-23T14:58:15.630896Z",
"url": "https://files.pythonhosted.org/packages/e9/e9/eb325605de84a642ec7da0a1cc52d95c478d1fd482ffdca309f62e7d375d/cdk-ec2-key-pair-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-23 14:58:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "udondan",
"github_project": "cdk-ec2-key-pair",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cdk-ec2-key-pair"
}
JSON
