Key management
In this section, you can find information about SSH keys, including how to generate them and how to rotate them.
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 use within AWS Transfer Family:
-
For ED25519:
ssh-ed25519
-
For RSA:
-
rsa-sha2-256
-
rsa-sha2-512
-
-
For ECDSA:
-
ecdsa-sha2-nistp256
-
ecdsa-sha2-nistp384
-
ecdsa-sha2-nistp521
-
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 user names 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.
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.
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.
-
To generate an RSA 4096-bit key pair:
ssh-keygen -t rsa -b 4096 -N "" -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 -N "" -f
key_name
-
To generate an ED25519 key pair:
ssh-keygen -t ed25519 -N "" -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 -N "" -f key_name Generating public/private rsa key pair. 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.
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
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
--gen-key
command to generate a key pair. Transfer Family supports key formats
and symmetric encryption algorithms that align with the OpenPGP RFC
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.
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
You can store a maximum of 3 keys, per Transfer Family server, per user.
To configure PGP keys for use with decryption
-
Generate a PGP key pair by running the following command and answering all of the prompts.
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, choose 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.
