Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Store SFTP server host keys in AWS Secrets Manager

Instead of letting Transfer Family manage your host key material, you can store the host keys for your SFTP-enabled server in a secret in AWS Secrets Manager (Secrets Manager). With Secrets Manager storage, Transfer Family stores the host key in a secret that you can encrypt with your own AWS Key Management Service (AWS KMS) key.

Choose Secrets Manager storage when you want to retrieve your host key material and reuse the same host key across servers and AWS Regions. You can also choose Secrets Manager storage when you want to encrypt your host key material with an AWS KMS key that you manage, or when you want to scope and audit access to the host key in Secrets Manager. To use Secrets Manager storage, set the storage type to SECRETS_MANAGER, as described in the following section.

Configure the host key storage type

You set the storage type when you create a server or when you import or update a host key. You can use the AWS Management Console, the AWS CLI, or the AWS API. In the AWS Transfer Family console, new servers default to AWS Secrets Manager storage. In the AWS CLI and the AWS API, new servers default to SERVICE_MANAGED storage if you don't set HostKeyStorageType. Transfer Family generates a host key for you if you don't provide one.

To encrypt the Secrets Manager secret with a customer managed key, set the optional KmsKey parameter to the Amazon Resource Name (ARN) of an AWS KMS key when you import or update the host key. If you don't specify a key, Transfer Family uses the AWS managed key for Secrets Manager. To change the key for a host key that already uses Secrets Manager storage, call UpdateHostKey with the new KmsKey, and Transfer Family re-encrypts the secret under the new key. To use a customer managed key, you must also update its key policy. For more information, see Grant access to a customer managed key.

The first time that you use Secrets Manager storage, Transfer Family creates the AWSServiceRoleForTransfer service-linked role in your account. Your IAM identity must have the iam:CreateServiceLinkedRole permission for this call. For more information, see Using service-linked roles for AWS Transfer Family.

The DescribeHostKey and ListHostKeys API operations report the StorageType of each host key. For a host key that uses Secrets Manager storage, the response also includes the SecretId of the Secrets Manager secret that holds the key material.

How Transfer Family manages the Secrets Manager secret

When you use Secrets Manager storage, Transfer Family creates a secret in your account with a name that begins with the transfer! prefix. Transfer Family uses the AWSServiceRoleForTransfer service-linked role to read the secret and serve the host key to incoming connections. For more information about this service-linked role, see Using service-linked roles for AWS Transfer Family.

Work with the Secrets Manager secret

The following list describes what you can and can't do with the Secrets Manager secret that Transfer Family creates for your host key:

Grant access to a customer managed key

If you encrypt the Secrets Manager secret with a customer managed key, the key policy must allow the Transfer Family service-linked role to call kms:Decrypt. The service-linked role's managed policy doesn't grant kms:Decrypt, so without this key policy statement Transfer Family can't read the host key material to serve it to incoming connections.

The following example key policy statement grants this access. The conditions limit the grant to calls that Secrets Manager makes on behalf of Transfer Family, for secrets whose names begin with transfer!. Replace 111122223333 with your AWS account ID and us-east-1 with your AWS Region. If your Region is in a partition other than aws, also replace arn:aws with the ARN prefix for your partition.

{
  "Sid": "Enable Transfer SLR to access",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:role/aws-service-role/transfer.amazonaws.com/AWSServiceRoleForTransfer"
  },
  "Action": "kms:Decrypt",
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "kms:ViaService": "secretsmanager.us-east-1.amazonaws.com"
    },
    "StringLike": {
      "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:us-east-1:111122223333:secret:transfer!*"
    }
  }
}