Key management - AWS Transfer Family
Supported algorithms for user and server keysGenerate SSH keysRotate SSH keys

Key management

In this section, you can find information about SSH keys, how to generate them, and how to rotate them.

Note

AWS Transfer Family accepts RSA, ECDSA, and ED25519 keys.

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

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 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.

To create SSH keys on a macOS, Linux, or UNIX operating system

  1. On macOS, Linux, or UNIX operating systems, open a command terminal.

  2. 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

    key_name is the SSH key pair file 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]-----+

  3. Navigate to the key_name.pub file and open it.

  4. Copy the text and paste it in SSH public key.

Note

When you run the ssh-keygen command as shown preceding, it creates the public and private keys as files in the current directory.

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 on creating SSH keys 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.

Console

To perform a key rotation in the console

  1. Open the AWS Transfer Family console at https://console.aws.amazon.com/transfer/.

  2. Navigate to the Servers page.

  3. Choose the identifier in the Server ID column to see the Server details page.

  4. Under Users, select the check box of the user whose SSH public key that you want to rotate, then choose Actions, and then choose Add key to see the Add key page.

    or

    Choose the user name to see the User details page, and then choose Add SSH public key to see the Add key page.

  5. Enter the new SSH public key and choose Add key.

    Important

    The format of the SSH public key depends on the type of key you generated.

    • For RSA keys, the format is ssh-rsa <string>.

    • For ED25519 keys, the format is ssh-ed25519 <string>.

    • For ECDSA keys, the key begins with ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521, depending on the size of the key you generated. The beginning string is then followed by <string>, similar to the other key types.

    You are returned to the User details page, and the new SSH public key that you just entered appears in the SSH public keys section.

  6. Select the check box of the old you key that you want to delete and then choose Delete.

  7. Confirm the deletion operation by entering the word delete, and then choose Delete.

API

To perform a key rotation using the API

  1. On macOS, Linux, or UNIX operating systems, open a command terminal.

  2. Retrieve the SSH key that you want to delete by entering the following command: 

    aws transfer describe-user --server-id='serverID' --user-name='username'

    where serverID is the Server ID for your Transfer Family server, and username is your user name.

    The command returns details about the user. Copy the contents of the "SshPublicKeyId": field: you need to enter this value later in this procedure. 

    "SshPublicKeys": [ { "SshPublicKeyBody": "public-key", "SshPublicKeyId": "keyID",
   "DateImported": 1621969331.072 } ],

  3. Next, import a new SSH key for your user. At the prompt, enter the following command: 

    aws transfer import-ssh-public-key --server-id='serverID' --user-name='username'
   --ssh-public-key-body='public-key'

    Where the public-key is the fingerprint of your new public key. If the command is successful, no output is returned.

  4. Finally, delete the old key by running the following command: 

    aws transfer delete-ssh-public-key --server-id='serverID' --user-name='username'
   --ssh-public-key-id='keyID-from-step-2'

    where keyID-from-step-2 is the key ID value you copied in step 2 of this procedure.

  5. (Optional) Repeat step 2, to confirm that the old key no longer exists.