SSH or SFTP into a Linux server from a Windows machine with key-based authentication

17 May 2022 🔖 windows linux intermediate tutorials security integration devops
💬 EN

SSH and SFTP are protocols typically used for “remoting into” a server running the Linux operating system, much like you might use the “Remote Desktop” protocol to remotely operate a Windows machine.

Although it can be authenticated into by username and password, many Linux servers force you to SSH/SFTP into them with a username and “key.”

• The Linux server will already have a copy of your “public key” on file (because you’ll have e-mailed it ahead of time to the server’s system administrator).
• It’ll be your job to keep a copy of your “private key” on the desktop computer from which you’ll be SSH’ing/SFTP’ing into the Linux machine.

Together, these are known as a “keypair.”

In this article, we’ll covering making a “keypair” if you don’t yet have one, and using it to SSH/SFTP into a Linux server, when your desktop computer runs Windows.

Generate a new Linux-style keypair

The first thing you’ll want to do is generate a “private key” file and a corresponding “public key” file, which together are known as a “keypair.”

Back in the day, most people who were remotely accessing Linux servers over SSH/SFTP were already typing at the command prompt of a computer running Linux. This is still the case for many Linux system administrators. Therefore, the tooling that people find most familiar for generating a “keypair” runs on Linux.

To ensure that people who really know what they’re doing with SSH/SFTP, like Linux system administrators, can help troubleshoot any problems you encounter when generating and using keypairs, a best practice is to use Linux-like software to initiate the generation of your keypair, even if you intend to use it from a Windows machine.

1: Install Linux-like software onto your Windows machine

Install some sort of sofware onto your Windows desktop that comes with the ability to run the Linux-style program named “ssh-keygen” at a command terminal.

Two great pieces of free software for Windows computers that give you a nice assortment of Linux-style commands like “ssh-keygen” are:

1. Windows Subsystem for Linux, a.k.a. “WSL”, accompanied by some sort of Linux installation obtained from the Microsoft Store.
   • (Coming soon, hopefully: my tutorial about how exactly to do that.)
2. The “Git Bash” terminal included in Git for Windows. When installed with its default settings, it runs in a mini-Linux-like environment called mingw

2: Generate a Linux-style private key file

Open up a WSL Linux command prompt and run the following Linux command, with a few edits:

ssh-keygen -f ~/.ssh/id_rsa -C "some_human_description@some_computer_description"

1. I’d replace “some_human_description” with “katiekodes.”
2. I’d replace “some_computer_description” with the phrase “desktopcomputer.”

So I’d be executing:

ssh-keygen -f ~/.ssh/id_rsa -C "katiekodes@desktopcomputer"

Secure your private key with a passphrase

When asked, “Enter passphrase (empty for no passphrase),” and again when asked, “Enter passphrase again,” type some sort of secret passphrase only you will ever know.

The purpose of the secret passphrase is to keep someone who steals files from your desktop’s hard drive, or sits down at your computer, from easily getting into our servers as if they were you.

There are probably more people who can do that than you think. Is this computer owned by your employer?

Congratulations, half of the computer-support technicians at the tech desk likely have “admin rights” to your computer, able to read the contents of any file on your computer that they’d like to read.

If you passphrase-protect your private key file (which will be sitting around on your desktop computer as an ordinary file), then even if someone steals a copy of it, they can’t actually use it to log into a server as if they were you unless they also know the passphrase.

3: Admire your new keypair

With Windows File Explorer, open the following folder:

\\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh

(Be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate.)

Validate that these two files exist:

1. id_rsa
   • This is your new Linux-style private key.
   • Don’t ever share the contents of this file with anyone.
2. id_rsa.pub
   • This is your new Linux-style public key.
   • The contents of this file are safe to e-mail to other people.

4: Back up your new keypair

Open up both of these files in Windows Notepad, copy their contents to your clipboard, and save them both into a secure password manager like LastPass.

Don’t skip this important step with a password manager. It’s crucial for accident recovery and for setting up a new desktop computer if you get yours replaced.

Give a sysadmin your public key

Email a copy of the file ending in “.pub” to the system administrator of the Linux server you’d like to be able to remote into.

If they don’t already know which Linux servers you’d like to be able to remote into, and as what Linux usernames on those Linux servers, let them know.

Test your Linux key against a Linux server

In your WSL Linux command prompt, run the following Linux command, substituting the location of your Linux-style private key file, the Linux username you’re trying to log into the server as, and the Linux server’s address on the internet as appropriate:

ssh the_linux_server_username_you_need_to_log_in_as@the_linux_server_domain_name_or_ip_address

If you did everything correctly on your machine, and if the Linux server’s system administrator has correctly put your public key into the server, then you should be prompted to enter the secret passphrase you chose for your key when you secured it. This is to prove that it’s really you sitting at your computer right now.

Once you type your passphrase and press Enter, your command prompt should look a little different, saying something like:

linux_username@server_name:/some/directory/path/<> $

To confirm that you’re no longer running commands against your local WSL Linux environment, and instead are running them on a remote Linux server, try executing a Linux command like:

pwd

You should you should see output that reminds you of the remote Linux server, like:

/some/directory/path

To log out of the remote Linux server and return to running commands against your own WSL Linux command line, execute the following command:

exit

You’re done! (Maybe.)

Congratulations, you are now able to SSH into a Linux server from a Windows computer!

That said, you might have a few other things you’re interested in doing, which is what the rest of the sections in this article will cover.

Make a Windows-friendly copy of the Linux-style private key

If you enjoy using point-and-click Windows software like WinSCP for SSH and SFTP, you’ll also want to do a few more things.

1: Install WinSCP onto your computer

Install WinSCP, which is free and comes with a crucial piece of software called “PuTTYgen” onto your Windows desktop.

2: Make a Windows-friendly key

1. Open WinSCP, and in the “Login” box that pops up upon opening, click the “Tools” button at the bottom left of the popup.
2. From the menu that appears, click “Run PuTTYgen.”
3. In the menu bar of the popup that appears titled “PuTTY Key Generator,” click “Conversions” and then click “Import key” below it.
4. Use the Windows Explorer file-browser popup that appears titled “Load private key” to find the Linux-style private key file you just generated and click “Open.”
   • If you used the instructions above, the private key file’s location on your hard drive should be something like this (be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate):

       \\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh\id_rsa
     

5. If you get a “Couldn't load private key” error, here are two troubleshooting ideas:
   • Uninstall WinSCP (and the PuTTy & PuTTYgen versions that its installer put onto your computer) and start over from scratch with a fresh WinSCP download. They fix bugs all the time.
   • If that fails, go see the “advanced pro tip” under “changing the secret passphrase on your private keys” section of this article. Sometimes that works. (Particularly with passphrase-protected Linux-style private keys generated by Git Bash instead of by WSL.)
6. When prompted “Enter passphrase for key,” prove that it’s really you sitting at your computer right now by typing the secret passphrase you made up earlier, and then click “OK.
7. Confirm that the “Key passphrase:” & “Confirm passphrase:” text boxes aren’t blank. (PuTTYgen should have filled them in for you based on the passphrase you just typed in.)
8. Click the button labeled “Save private key”.
   
9. In the “File name:” text box of the Windows Explorer file-browser popup that appears titled “Save private key as,” give it the following filename (be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate):

    \\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh\id_rsa.ppk
   

   • Be careful not to accidentally overwrite the file called “id_rsa” without a file extension. Make sure this new file has a “.ppk” file extension.
   • Honestly, you could save it anywhere on your hard drive and give it any filename you like, but hey, you might as well save it near near your Linux-style keys with a similar naming pattern.
10. You can close PuTTYGen (the popup that appears titled “PuTTY Key Generator”) now.

3: Admire your new keypair

With Windows File Explorer, open the following folder:

\\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh

(Be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate.)

Validate that this third file now also exists:

• id_rsa.ppk
  • This is your new Windows-style private key.
  • Don’t ever share the contents of this file with anyone.

4: Back up your new keypair

Open up this third files in Windows Notepad, copy its contents to your clipboard, and save it into a secure password manager like LastPass.

Don’t skip this important step with a password manager. It’s crucial for accident recovery and for setting up a new desktop computer if you get yours replaced.

Test your Windows key against a Linux server

1. Open WinSCP, and in white area at the top of the “Login” box that pops up upon opening, click the “New Site” icon.
2. At right, in the “Session” area, put “the_linux_server_domain_name_or_ip_address” (modifying as appropriate) into “Host name”, “the_linux_server_username_you_need_to_log_in_as” into “User name”, and then click the “Advanced” button, and at left under “SSH,” click “Authentication.”
3. At right, click the three dots in the box under “Private key file” and choose your Windows-style private key file that ends in “.ppk”.
   • If you were following these instructions, it lives somewhere like this (be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate):

       \\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh\id_rsa.ppk
     

4. Click “OK” to close the advanced popup.
5. Click the “Login” button.
   • You should get prompted for your secret passphrase to prove that it’s really you sitting at your computer right now.
   • And then you should get SFTP’ed into the server!
6. To SSH into the server, click Commands followed by Open in PuTTY.
   • In the terminal window that pops up, type your secret passphrase again.
   • You should now be SSH’ed into the server and able to run commands like “pwd”!</li>
   • Execute the exit command to close your PuTTY session.

You’re probably done now

OK, a few more tricks below…

Changing the secret passphrase on your private keys

If you ever decide that you hate the secret passphrase you came up with to protect your private keys, or if you forgot to set a secret passphrase at all when you generated it, it’s pretty easy to change or add a private key’s secret passphrase.

1: Re-passphrase your Linux-style private key

Open up a WSL Linux command prompt and run the following Linux command, with a few edits:

ssh-keygen -f ~/.ssh/id_rsa -C "some_human_description@some_computer_description" -p

1. I’d replace “some_human_description” with “katiekodes.”
2. I’d replace “some_computer_description” with the phrase “desktopcomputer.”

So I’d be executing:

ssh-keygen -f ~/.ssh/id_rsa -C "katiekodes@desktopcomputer" -p

You’ll be prompted for your old passphrase and for a new passphrase you’d like to use instead.  Once you’re done, the “id_rsa” file (your Linux-style private key file) will be passphrase-protected with your new private key.

2: Re-passphrase your Windows-style private key

To edit the passphrase on your Windows-style private key file (“id_rsa.ppk”) to match, there’s probably some way of doing it directly, but just as easy is to simply delete the “id_rsa.ppk” file altogether and re-generate it from the new version of the “id_rsa” file.

To re-generate it, just follow the original PuTTYgen instructions for making a Windows-style private key file out of a Linux-style private key file.

3: Test your keys again

1. Re-test logging into a server with the “ssh” Linux command from a WSL Linux command prompt.
   • Make sure that you get prompted for your new passphrase.
2. Re-test logging into a server with WinSCP.
   • Make sure that you get prompted for your new passphrase.

4: Back up your new passphrase and private keys

Be sure to update your secure password manager (e.g. LastPass) notes with:

1. the latest version of your passphrase
2. the latest contents of your Linux-style private key file (“id_rsa“)
   • (Remember, be careful not to accidentally save it if you open it in a Windows-based text editor)
3. the latest contents of your Windows-style private key file (“id_rsa.ppk“)

Advanced PuTTYgen pro tip

Sometimes, when PuTTYgen doesn’t like your Linux-style private key while generating a Windows-style private key (when you click “open” after choosing the “id_rsa” file, it says “Couldn’t load private key“), you can do this:

1. Change the Linux-style passphrase to nothing at all, using this technique.
2. Now try generating your Windows-style private key file in PuTTYgen from the un-passphrase-protected “id_rsa” Linux-style private key file with the directions above.
   • Note that you’ll have to enter a passphrase to protect your Windows-style private key file manually into the “Key passphrase:” & “Confirm passphrase:” text boxes, instead of PuTTYgen figuring it out for you from the Linux-style passphrase, since you won’t be working with a passphrase.
3. Test that your Windows-style private key file gets you into servers with WinSCP, and that you get prompted for a passphrase when you try to log into a server through WinSCP.
4. Change the Linux-style passphrase back from nothing to an actual passphrase, using this technique.
5. Test that you can still “ssh” into servers from your WSL Linux command line as described above, and that you get prompted for a passphrase when you do.

Honestly, though, don’t try this until you’re sure that you have WinSCP, PuTTY, & PuTTYgen up-to-date.

They seem to have fixed a lot in recent versions, and you probably won’t have to do this if you’re on the latest versions.

Migrating your keys to a new computer

1: Lay the groundwork

When you get your new computer, open your WSL Linux command line.

Check if your WSL Linux main user’s home directory already has a “.ssh” folder:

ls -l -d ~/.ssh

If not, create it:

mkdir ~/.ssh

2: Import your Linux-style private key

Create a new file and open it for editing with the following command:

vi ~/.ssh id_rsa

The contents of the file should be empty, as this should be a new computer and you should have just created this file.

1. Type “i” when inside the VIM editor to go into “insert mode” where you can type.
2. Copy the contents of your Linux-style private key from your secure password manager (e.g. LastPass) onto your clipboard. Don’t copy excess whitespace.
3. Right-click into the VIM editor’s blank space to paste the contents of your clipboard into the editor.
4. Hit “esc” to exit “insert mode” and go back to the VIM editor’s command mode.
5. To save and exit VIM and return to your WSL Linux command line, type the following: “:wq” followed by “enter”.

You can validate that you got the contents of your Linux-style private key into the “id_rsa” file with the following command:

cat ~/.ssh/id_rsa

You’re not quite done yet.

Linux’s “ssh” command is going to yell at you for the permissions of this file, seeing as it’s a private key, so next, run this Linux command:

chmod g-r,o-r ~/.ssh/id_rsa

You can verify that the file’s permissions are now “-rw------” at the far left of the output that you see from running this Linux command:

ls -la ~/.ssh/id_rsa

Now your Linux-style private key is ready to use.

Test your Linux-style private key

Now that you’ve imported your Linux-style private key onto your new computer, test executing the “ssh” command from within your new computer’s WSL Linux command prompt the way you did when you first generated the key.

2: Import your Windows-style private key

Create a new “id_rsa.ppk” file and open it for editing.

It doesn’t matter if you use VIM like above, or if you use Windows Notepad.

1. If you use a Linux command like VIM, you’ll be saving it to a Linux-style filepath of “~/.ssh/id_rsa.ppk”.
2. If you use a point-and-click Windows text editor like Notepad or Notepad++, you’ll be saving it to a Windows-style filepath like this (be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate):

    \\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh\id_rsa.ppk
   

Either way, copy the contents of your Windows-style private key from your secure password manager onto your clipboard. Don’t copy excess whitespace.

Then paste it into the text editor and save your work.

Now your Windows-style private key is also ready to use.

Test your Windows-style private key

Now that you’ve imported your Windows-style private key onto your new computer, test connecting to a server with WinSCP the way you did when you first generated the key.

If this is a new computer, you might have to freshly install WinSCP and set up all of your favorite servers all over again.

3: Import your Linux-style public key

Create a new “id_rsa.pub” file and open it for editing.

It doesn’t matter if you use VIM like above, or if you use Windows Notepad.

1. If you use a Linux command like VIM, you’ll be saving it to a Linux-style filepath of “~/.ssh/id_rsa.pub”.
2. If you use a point-and-click Windows text editor like Notepad or Notepad++, you’ll be saving it to a Windows-style filepath like this (be sure to swap out “your_linux_operating_system_name” and “your_wsl_username” as appropriate):

    \\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh\id_rsa.pub
   

Either way, copy the contents of your public key from your secure password manager onto your clipboard. Don’t copy excess whitespace.

Then paste it into the text editor and save your work.

On naming things

Power user who wants different keypairs for different work contexts? Cool!

You don’t have to follow the folder-and-file standards I’ve used in this example when it comes to the plaintext files that hold copies of:

1. your Linux-style private key
2. your Windows-style private key
3. your Linux-style public key

You have my blessing to name these files anything you want, and to put them anywhere on your computer that you want.

That’s one reason I included an “-f” parameter, as in “-f ~/.ssh/id_rsa,” in my example calls to “ssh-keygen”. Just change the Linux filepath “~/.ssh/id_rsa” to something else.

If you want to store them under the Windows C:\example\my_keys instead of \\wsl$\your_linux_operating_system_name\home\your_wsl_username\.ssh, cool. In WSL, that’d be your /mnt/c/example/my_keys folder instead of your ~/.ssh folder.

If you want to invoke the WSL “ssh” command against some sort of custom private key filepath instead of “~/.ssh/id_rsa,” just give it an “-i” flag like this:

ssh -i "/mnt/c/example/my_keys/my_day_job_private_key.txt" username_on_server@server_domain_or_ip