Key pair actions

Objective

Key pairs are how SSH access to an instance is established. We hold public keys only.

Permissions

Action	Resource scope
ec2:CreateKeyPair	key-pair/*
ec2:ImportKeyPair	key-pair/*
ec2:DescribeKeyPairs	Requires "Resource": "*"
ec2:DeleteKeyPair	key-pair/<name>

Instructions

CreateKeyPair

Generates a pair and returns the private key once.

Parameter	Type	Required	Notes
KeyName	string	Yes	Unique within the account, 1–255 characters
KeyType	string	No	ed25519 or rsa. PROPOSED: default ed25519
TagSpecification.N	list	No
DryRun	boolean	No

Response: keyName, keyFingerprint, keyPairId, and keyMaterial — the PEM-encoded private key.

<CreateKeyPairResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>b1e2c3d4-5678-90ab-cdef-1234567890ab</requestId>
  <keyName>laptop</keyName>
  <keyPairId>key-0a1b2c3d4e5f60718</keyPairId>
  <keyFingerprint>1f:51:ae:28:bf:89:e9:d8:1f:25:5d:37:2d:7d:b8:ca</keyFingerprint>
  <keyMaterial>-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----</keyMaterial>
</CreateKeyPairResponse>

[!warning]

keyMaterial appears in this response and nowhere else. We do not store it in a recoverable form. Losing it means every instance launched with this key pair becomes unreachable, and there is no console through which to recover one.

Not idempotent. No ClientToken exists on this action, so a retry after a lost response generates a second, different key pair — and the private key from the first response is gone. Prefer ImportKeyPair, which is safe to retry.

Errors

Code	Status	Cause
InvalidKeyPair.Duplicate	400	That name already exists
InvalidParameterValue	400	Name too long, or an unsupported key type
KeyPairLimitExceeded	400	A quota would be exceeded

ImportKeyPair

Registers a public key you already hold. The recommended path: your private key never crosses the network.

Parameter	Type	Required	Notes
KeyName	string	Yes
PublicKeyMaterial	blob	Yes	Base64 of an OpenSSH or RFC 4716 public key
TagSpecification.N	list	No

Response: keyName, keyFingerprint, keyPairId. No key material, because we never had the private half.

Importing the same key under the same name twice returns InvalidKeyPair.Duplicate; importing the same key under a different name is permitted, and produces two key pairs with the same fingerprint.

DescribeKeyPairs

Parameter	Type	Notes
KeyName.N	list
KeyPairId.N	list
Filter.N	list	key-name, fingerprint, tag:<key>

Response: for each, keyName, keyPairId, keyFingerprint, createTime, tagSet.

There is no action that returns a private key. None exists to be called, in this API or any other, because we hold none.

Not paginated — key pair counts are bounded by a quota small enough that paging would add complexity without protecting anything.

DeleteKeyPair

Parameter	Type	Required
KeyName or KeyPairId	string	Yes, one of them

Removes our copy of the public key.

It does not remove the key from running instances. The public key was written into the instance at first boot and lives in that instance’s authorized_keys. Anyone holding the private key keeps access after deletion.

To actually revoke access to a running instance, remove the key from authorized_keys inside the instance. Deleting the key pair only prevents future launches from using it.

Deleting a key pair that does not exist succeeds — this action is one of the few that does not return not-found, matching Amazon EC2’s behaviour.

Go further

• Key pairs
• RunInstances