Key management
In this section, you can find information about SSH keys, including how to generate them and how to rotate them.
Note
AWS Transfer Family accepts RSA, ECDSA, and ED25519 keys.
This section also covers how to generate and manage Pretty Good Privacy (PGP) keys.
Topics
Supported algorithms for user and server keys
The following key algorithms are supported for user and server key-pairs within AWS Transfer Family.
Note
For algorithms to use with PGP decryption in workflows, see Algorithms supported for PGP key-pairs.
-
For ED25519:
ssh-ed25519
-
For RSA:
-
rsa-sha2-256
-
rsa-sha2-512
-
-
For ECDSA:
-
ecdsa-sha2-nistp256
-
ecdsa-sha2-nistp384
-
ecdsa-sha2-nistp521
-
Note
We support ssh-rsa
with SHA1 for our older security policies (all policies except for
TransferSecurityPolicy-2022-03).
Generate SSH keys
You can set up your server to authenticate users using the service managed authentication method, where usernames and SSH keys are stored within the service. The user's public SSH key is uploaded to the server as a user's property. This key is used by the server as part of a standard key-based authentication process. Each user can have multiple public SSH keys on file with an individual server. For limits on number of keys that can be stored per user, see the AWS service quotas in the AWS General Reference.
As an alternative to the service managed authentication method, you can authenticate users using a custom identity provider. This allows you to plug in an existing identity provider using an Amazon API Gateway endpoint. For more information, see Authenticating using an API Gateway method.
A server can only authenticate users using one method (service managed or custom identity provider), and that method cannot be changed after the server is created.
Topics
Creating SSH keys on macOS, Linux, or Unix
On the macOS, Linux, or Unix operating systems, you use the
ssh-keygen
command to create an SSH public key and SSH private
key also known as a key pair.
Note
For a tutorial on creating SSH keys using PuTTYgen on Windows, see the
SSH.com
website.
To create SSH keys on a macOS, Linux, or Unix operating system
-
On macOS, Linux, or Unix operating systems, open a command terminal.
-
AWS Transfer Family accepts RSA-, ECDSA-, and ED25519-formatted keys. Choose the appropriate command based on the type of key-pair you are generating.
Note
In the following examples, we do not specify a passphrase: in this case, the tool asks you to enter your passphrase and then repeat it to verify. Creating a passphrase offers better protection for your private key, and might also improve overall system security. You cannot recover your passphrase: if you forget it, you must create a new key.
However, if you are generating a server host key, you must specify an empty passphrase, by specifying the
-N ""
option in the command (or by pressingEnter
twice when prompted), because Transfer Family servers cannot request a password at start-up.-
To generate an RSA 4096-bit key pair:
ssh-keygen -t rsa -b 4096 -f
key_name
-
To generate an ECDSA 521-bit key-pair (ECDSA has bit sizes of 256, 384, and 521):
ssh-keygen -t ecdsa -b 521 -f
key_name
-
To generate an ED25519 key pair:
ssh-keygen -t ed25519 -f
key_name
Note
is the SSH key pair file name.key_name
The following shows an example of the
ssh-keygen
output.ssh-keygen -t rsa -b 4096 -f key_name Generating public/private rsa key pair. Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in key_name. Your public key has been saved in key_name.pub. The key fingerprint is: SHA256:8tDDwPmanTFcEzjTwPGETVWOGW1nVz+gtCCE8hL7PrQ bob.amazon.com The key's randomart image is: +---[RSA 4096]----+ | . ....E | | . = ... | |. . . = ..o | | . o + oo = | | + = .S.= * | | . o o ..B + o | | .o.+.* . | | =o*+*. | | ..*o*+. | +----[SHA256]-----+
Note
When you run the
ssh-keygen
command as shown preceding, it creates the public and private keys as files in the current directory. -
-
Navigate to the
file and open it.key_name
.pub -
Copy the text and paste it in SSH public key for the service-managed user.
-
Open the AWS Transfer Family console at https://console.aws.amazon.com/transfer/
, then select Servers from the navigation pane. -
On the Servers page, select the Server ID for server that contains the user that you want to update.
-
Select the user for which you are adding a public key.
-
In the SSH public keys pane, choose Add SSH public key.
-
Paste the text of the public key you generated into the SSH public key text box, and then choose Add key.
The new key is listed in the SSH public key pane.
-
Creating SSH keys on Microsoft Windows
Windows uses a slightly different SSH key pair format. The public key must be
in the PUB
format, and the private key must be in the
PPK
format. On Windows, you can use PuTTYgen to create an SSH
key pair in the appropriate formats. You can also use PuTTYgen to convert a
private key generated using ssh-keygen
to a
.ppk
file.
Note
If you present WinSCP with a private key file not in
.ppk
format, that client offers to convert the key
into .ppk
format for you.
For a tutorial about creating SSH keys by using PuTTYgen on Windows, see the
SSH.com
website
Convert an SSH2 public key to OpenSSH format
AWS Transfer Family only accepts OpenSSH formatted public keys. If you have an SSH2 public key, you need to convert it. An SSH2 public key has the following format:
---- BEGIN SSH2 PUBLIC KEY ---- Comment: "rsa-key-20160402" AAAAB3NzaC1yc2EAAAABJQAAAgEAiL0jjDdFqK/kYThqKt7THrjABTPWvXmB3URI : : ---- END SSH2 PUBLIC KEY ----
An OpenSSH public key has the following format:
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAA...
Run the following command to convert an SSH2-formatted public key into an
OpenSSH-formatted public key. Replace ssh2-key
with
the name of your SSH2 key, and openSSH-key
with the
name of your OpenSSH key.
ssh-keygen -i -f
ssh2-key
.pub >openSSH-key
.pub
Rotate SSH keys
For security, we recommend the best practice of rotating your SSH keys. Usually, this rotation is specified as a part of a security policy and is implemented in some automated fashion. Depending upon the level of security, for a highly sensitive communication, an SSH key pair might be used only once. Doing this eliminates any risk due to stored keys. However, it is much more common to store SSH credentials for a period of time and set an interval that doesn't place undue burden on users. A time interval of three months is common.
There are two methods used to perform SSH key rotation:
-
On the console, you can upload a new SSH public key and delete an existing SSH public key.
-
Using the API, you can update existing users by using the DeleteSshPublicKey API to delete a user's Secure Shell (SSH) public key and the ImportSshPublicKey API to add a new Secure Shell (SSH) public key to the user's account.
Generate and manage PGP keys
You can use Pretty Good Privacy (PGP) decryption with the files that Transfer Family processes with workflows. To use decryption in a workflow step, you must provide a PGP key.
Generate PGP keys
The method that you use to generate your PGP keys depends on your operating system and the version of the key-generation software that you're using.
If you're using Linux or Unix, use your package installer to install
gpg
. Depending on your Linux distribution, one of the following
commands should work for you.
sudo yum install gnupg
sudo apt-get install gnupg
For Windows or macOS, you can download what you need from https://gnupg.org/download/
After you install your PGP key generator software, you run the gpg
--full-gen-key
or gpg --gen-key
command to generate a
key pair.
Note
If you're using GnuPG
version 2.3.0 or newer, you
must run gpg --full-gen-key
. When prompted for the type of key
to create, choose RSA or ECC. However, if you choose ECC, make sure to choose either
NIST or BrainPool for the elliptic curve.
Do not choose Curve 25519.
Algorithms supported for PGP key-pairs
The following algorithms are supported for PGP key pairs:
-
RSA
-
Elgamal
-
ECC:
-
NIST
-
BrainPool
-
Note
Curve25519 keys are not supported.
Useful gpg
subcommands
The following are some useful subcommands for
gpg
:
-
gpg --help
– This command lists the available options and might include some examples. -
gpg --list-keys
– This command lists the details for all of the key pairs that you have created. -
gpg --fingerprint
– This command lists the details for all of your key pairs, including each key's fingerprint. -
gpg --export -a
– This command exports the public key portion of the key for theuser-name
that was used when the key was generated.user-name
Manage PGP keys
To manage your PGP keys, you must use AWS Secrets Manager.
Note
Your secret name includes your Transfer Family server ID. This means you should have already identified or created a server before you can store your PGP key information in AWS Secrets Manager.
If you want to use one key and passphrase for all of your users, you can store
the PGP key block information under the secret name
aws/transfer/
,
where server-id
/@pgp-default
is the ID for your Transfer Family
server. This default key is used if there is no key where the
server-id
matches the user that
is executing the workflow. user-name
Alternatively, you can create a key for a specific user. In this case, the
format for the secret name is
aws/transfer/
,
where server-id
/user-name
matches the user that is
running the workflow for a Transfer Family server.user-name
Note
You can store a maximum of 3 PGP private keys, per Transfer Family server, per user.
To configure PGP keys for use with decryption
-
Depending on the version of GPG that you are using, run one of the following commands to generate a PGP key pair that does not use a Curve 25519 encryption algorithm.
-
If you are using
GnuPG
version 2.3.0 or newer, run the following command:gpg --full-gen-key
You can choose
RSA
, or, if you chooseECC
, you can choose eitherNIST
orBrainPool
for the elliptic curve. If you rungpg --gen-key
instead, you create a key pair that uses the ECC Curve 25519 encryption algorithm, which we don't currently support for PGP keys. -
For versions of
GnuPG
prior to 2.3.0, you can use the following command, since RSA is the default encryption type.gpg --gen-key
Important
During the key-generation process, you must provide a passphrase and an email address. Make sure to take note of these values. You must provide the passphrase when you enter the key's details into AWS Secrets Manager later in this procedure. And you must provide the same email address to export the private key in the next step.
-
-
Run the following command to export the private key. To use this command, replace
with the name of the file in which to save the private key block, andprivate.pgp
with the email address that you used when you generated the key pair.marymajor@example.com
gpg --output
private.pgp
--armor --export-secret-keymarymajor@example.com
-
Use AWS Secrets Manager to store your PGP key.
-
Sign in to the AWS Management Console and open the AWS Secrets Manager console at https://console.aws.amazon.com/secretsmanager/
. -
In the left navigation pane, choose Secrets.
-
On the Secrets page, choose Store a new secret.
-
On the Choose secret type page, for Secret type, select Other type of secret.
-
In the Key/value pairs section, choose the Key/value tab.
-
Key – Enter
PGPPrivateKey
.Note
You must enter the
PGPPrivateKey
string exactly: do not add any spaces before or between characters. -
value – Paste the text of your private key into the value field. You can find the text of your private key in the file (for example,
private.pgp
) that you specified when you exported your key earlier in this procedure. The key begins with-----BEGIN PGP PRIVATE KEY BLOCK-----
and ends with-----END PGP PRIVATE KEY BLOCK-----
.Note
Make sure that the text block contains only the private key and does not contain the public key as well.
-
-
Select Add row and in the Key/value pairs section, choose the Key/value tab.
-
Key – Enter
PGPPassphrase
.Note
You must enter the
PGPPassphrase
string exactly: do not add any spaces before or between characters. -
value – Enter the passphrase you used when you generated your PGP key pair.
Note
You can add up to 3 sets of keys and passphrases. To add a second set, add two new rows, and enter
PGPPrivateKey2
andPGPPassphrase2
for the keys, and paste in another private key and passphrase. To add a third set, key values must bePGPPrivateKey3
andPGPPassphrase3
. -
-
Choose Next.
-
On the Configure secret page, enter a name and description for your secret.
-
If you're creating a default key, that is, a key that can be used by any Transfer Family user, enter
aws/transfer/
. Replaceserver-id
/@pgp-default
with the ID of the server that contains the workflow that has a decrypt step.server-id
-
If you're creating a key to be used by a specific Transfer Family user, enter
aws/transfer/
. Replaceserver-id
/user-name
with the ID of the server that contains the workflow that has a decrypt step, and replaceserver-id
with the name of the user that's running the workflow. Theuser-name
is stored in the identity provider that the Transfer Family server is using.user-name
-
-
Choose Next and accept the defaults on the Configure rotation page. Then choose Next.
-
On the Review page, choose Store to create and store the secret.
-
The following screenshot shows the details for the user
marymajor
for a specific Transfer Family server. This example
shows three keys and their corresponding passphrases.

Supported PGP clients
The following clients have been tested with Transfer Family and can be used to generate PGP keys, and to encrypt files that you intend to decrypt with a workflow.
-
Gpg4win + Kleopatra.
Note
When you select Sign / Encrypt Files, make sure to clear the selection for Sign as: we do not currently support signing for encrypted files.
-
Major GnuPG versions: 2.4, 2.3, 2.2, 2.0, and 1.4.
Note that other PGP clients might work as well, but only the clients mentioned here have been tested with Transfer Family.