Using SSH keys with SFTP

Updated 4 months ago by James Dunn

Password Authentication

This is the default authentication method. When connecting via SFTP, if key authentication is not set up the user will be prompted for a password.

Key Authentication

If you wish to use publickey authentication, upload your public key(s) into the .ssh folder using SFTP with Password Authentication.

The format supported is the OpenSSH format, which is typically a file named "id_rsa.pub" or similar. Within the file you will find a single line such as:

ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAgkdc1nQnrj2DXUJhTN3F2ohbL46Cdhc26kgkgQpknF
UT7edP3H+GHaR9avmHClr03L9ZZy7ERaHf0v7lwjnisnQjzFphrCFcGW5H/aLy9Raz7Lnf4ntNmdRY
jHAf1wzT0vUxk/G/kD00xZ1KEJWrzm0ld3JQwHNHN6FcKx6803IXT8DglR7HAAKIyF2az5YGFal5EX
AK7PKkf4I6Yl3l7u4zUmzBWbtruXWdnbj6qk6qMhN5rPPQIjrbPluziMyLBDfbKln2uzo7rpX/YHE3
PZLOlUWhBRdNHJl2zk9fnxm8TNW8gd45bzuRnXELBJJsfqclLcQMuxxOcMPYheyR1Q== rsa-key-2
0200410
In the following examples, replace "YourCompanySiteAddress.com" with the your FTP server address.

How-to Generate a Key Pair on macOS or Linux using OpenSSH

  1. Open the Terminal and run the following commands:
$ cd ~/.ssh
$ ssh-keygen -f sftp
  1. You should get the following response:
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in sftp.
Your public key has been saved in sftp.pub.
The key fingerprint is:
SHA256:n8mulp5MG3dAfNEvUPRWG0UaTIs6JK56Lo+dLWpm0uo username@YourCompanySiteAddress.com
The key's randomart image is:
+---[RSA 2048]----+
|            .*=o=|
|         .  .oo=+|
|        . + o.ooo|
|       . + o  ...|
|        S +    . |
|       . o =     |
|   .  . o.* .    |
|  . *+o=o* .     |
| .E*+*=+B..      |
+----[SHA256]-----+
The passphrase is optional but using it provides a second factor of security.
If you choose to use a passpharase, you will be prompted to enter this each time you login, like traditional password, except it is validated on your computer and not on the server.
Getting the passphrase wrong will not lock you out, but if you forget it, you'll need to create new keys and start this process over.
The sftp.pub file contains the public key. You can rename this file how you like, so long as it ends in ".pub".
The private key does not end in .pub. In this example it is simply "sftp". You may also see "id_rsa" if you have a key already generated.
  1. This file should be uploaded into the .ssh folder using SFTP with Password Authentication.
This file should only contain one (1) public key only. If a user needs multiple keys (E.g. different workstations) make a new file with a different name, ending in ".pub" and upload it.

The sftp file should be used by the SFTP client to connect.

How-to Generate a Key Pair on Windows using PuTTY

  1. Open PuttyGen.exe from the Start Menu.
  2. Enter "2048" in the field at the bottom for the number of bits,
  3. Select the type "RSA" if it is not selected already.
  4. Click the Generate button and move your mouse around when prompted to.
The passphrase is optional but using it provides a second factor of security.
If you choose to use a passpharase, you will be prompted to enter this each time you login, like traditional password, except it is validated on your computer and not on the server.
Getting the passphrase wrong will not lock you out, but if you forget it, you'll need to create new keys and start this process over.
  1. Select the generated text and right click to copy it to your clipboard.
  1. Open Notepad.exe from the Start Menu.
  2. Paste the key into the blank area.
  3. Click File > Save as...
    1. Name this file anything you like as long as it ends in .pub
For the rest of this example we will refer to this file as "authorized_keys.pub"
Best practice is to save these keys in your home directory on your system, in a subfolder called .ssh (the leading dot makes it a hidden folder) Since it is a hidden folder, it may be easier to type the path manually, than to Browse if you are not set up to show hidden files on your system.
  1. Now, click Save Public Key and follow the prompts to save the file.
For the rest of this example we will refer to this file as "sftp.pub"
  1. Click Save Private Key and follow the prompts to save the file as before.
For the rest of this example we will refer to this file as "sftp.ppk"
  1. Connect via SFTP with Password Authentication.
psftp username@YourCompanySiteAddress.com
  1. Upload the file authorized_keys.pub into the .ssh directory.
put authorized_keys.pub /.ssh/authorized_keys.pub
  1. Close the connection.
bye
Do not upload the sftp.pub file as that is in an unsupported (PuTTY) format.
Do not upload the sftp.ppk file as that is your private key. (Keep it secret. Keep it safe.)

Examples of Usage

PuTTY (Windows)

psftp -i .ssh/sftp.ppk username@YourCompanySiteAddress.com

WinSCP (Windows)

WS_FTP Pro (Windows)

Command Line Interface (BSD)

$ sftp -i ~/.ssh/sftp username@YourCompanySiteAddress.com

Troubleshooting Setup

If unable to upload the public key file, ensure...

  1. You are logged in via SFTP on port 22. It's not designed to work through FTP(S) or the web interface for security.
  2. The SFTP credentials match the user to whom the SSH key belongs. The /.ssh folder is private and unique to each user, so even an admin cannot access it without changing the user's password.
  3. The public key file you upload should be in OpenSSH format and not PuTTY format.
    1. To check you can open the public key file up in a text editor.
      In PuTTY format the first line will look like this:
      ---- BEGIN SSH2 PUBLIC KEY ----
      In OpenSSH format everything is on line 1 and it begins like this:
      ssh-rsa AAA
    2. The following command will convert a PuTTY key to OpenSSH:
      $ ssh-keygen -i -f sftp_putty.pub > sftp_openssh.pub

How Did We Do?