Salesforce, Python, SQL, & other ways to put your data where you need it

Need event music? 🎸

Live and recorded jazz, pop, and meditative music for your virtual conference / Zoom wedding / yoga class / private party with quality sound and a smooth technical experience

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

Table of Contents

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

The rest of these instructions will proceed with the presumption that you’re using WSL and a Linux OS installed into it, because Linux-style private keys generated with Git Bash can be a bit finicky when imported into PuTTYgen to turn them into Windows-style private keys.

Greek to you? That sentence will make more sense after you’ve followed all of the instructions.

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"

The part after -C is just a comment that will show up when you send your public key to a Linux server’s system administrator.

You probably won’t be the only person who’s ever sent them a public key, so doing them a favor and putting in a comment briefly describing who you are, and what kind of computer you keep the corresponding private key on, is handy when they’re wading through everyone’s files.

For example, if you ever tell them that you generated a new keypair, and ask them to make it so that your old keys can’t be used to access the server, it’ll really help for you to have put a comment into your public key that identifies which key you’re talking about.

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.

You’ll be typing it frequently if you work with servers over SSH/SFTP a lot, so it’s fine for it to be long but easy to type (like a sentence joking about how annoying all these steps were).

See the “correct horse battery staple” principle from the cartoon XKCD to learn more about why I recommend this.

Make it something brand new, though.

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.

Be sure to save this passphrase into a secure password manager like LastPass and to label it well so that you can find it later.

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

You can open this folder in Windows explorer by opening the Windows Start Menu, starting to type “\\wsl$\”, and hitting “Enter.” Then navigate through the subdirectories by double-clicking on them until you find the one above, just like you might if you were exploring your “C:\” drive’s files.

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.

Be careful not to accidentally Save the “id_rsa” file when you have it open in Notepad for copying its contents.

Saving the file with a Windows-based text editor with its “permissions” in a way that make it impossible to use for actual “ssh” operations performed within your WSL Linux environment.


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

The first time you connect to a given server, your Linux environment might ask if you’re sure that the server’s fingerprint is really valid.

If it’s an internal server that your company maintains, you’re probably safe to just say “yes.”

That said, you’re welcome to ask the server’s sysadmin what the legitimate fingerprint is if you’re really skeptical & cautious.

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

Note that this is just a “ -p” added to the end of the same command originally used to generate a Linux-style keypair.

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“)

You shouldn’t need to do anything with the latest contents of your Linux-style public key file (“id_rsa.pub“).

Whatever your public key already was (and that you sent to server sysadmins) should still be completely compatible with the changes you just made to your private keys.

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.

That said, you can’t install WSL into Windows without admin rights to your computer, whereas you definitely can install Git Bash into Windows without admin rights to your computer.

Git Bash’s version of “ssh-keygen,” as of the time this article was written, seems to generate Linux-style private keys that PuTTYgen – even modern versions – can’t import properly if they’re password-protected.

So this workaround can be useful for getting yourself going if the only thing you have available to you for running “ssh-keygen” is Git Bash.

(As to where your key files will actually live if using Git Bash’s “ssh-keygen” against these instructions, you should know that the Linux-style “home folder” of “~” in Git Bash is a shorthand for the Git Bash folder “/c/Users/your_windows_username,” which is the Windows folder “C:\Users\your_windows_username\”. Git Bash doesn’t create a separate, deciated “Linux user home folder” like WSL does at “\\wsl$\...”. Git Bash just uses your Windows user folder as its “Linux” home folder.)


Migrating your keys to a new computer

These directions are also handy for editing the contents of your “id_rsa,” “id_rsa.ppk,” and “id_rsa.pub” files, to fix them, if you accidentally overwrote them with something you didn’t mean to overwrite them with

Only in that scenario, you might have some backspacing-out of garbage to do when you open the files in a text editor like VIM or Notepad.

Also, don’t forget that “id_rsa” can only be safely edited in a Linux text editor like VIM. (The “.ppk” and “.pub” files can be edited any text editor software you like.)

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

Sadly, if you try to create or edit “id_rsa with, say, Windows Notepad, it’ll mess up the Linux-style file permissions of that file. Any attempt to run the “ssh” command will yell at you for not having proper file permissions for the file containing your Linux-style private key.

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.

Forget to save a copy of your Windows-style private key into your password manager?

If you managed to migrate your Linux-style private key to the new computer, no worries.

Just generate a new Windows-style one from the Linux-style one like the very first time you generated the Windows-style one.

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.

Honestly, you don’t even need to keep a copy of your public key on your computer.

Some people just find it handy to have it saved on their desktop computer near the private keys it accompanies.


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.

Just make sure that you don’t try to rename or move a Linux-style private key file from Windows.

Instead, you’ll want to move and rename files within WSL with Linux commands.

Otherwise, calls to “ssh” might yell at you about the permissions settings of that your Linux-style private key file not being “-rw------”.

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

Actually, now that I think about it, you might have issues with /mnt/c-style paths … I’m not sure it’s possible to get the default setup of WSL to let any files stored on things like your “C drive” be in “-rw------” mode in Linux.

Maybe if you want to use the WSL “ssh” command rather than sticking to WinSCP and such, you might have to keep a copy of your Linux-style private key somewhere under “\\wsl$\your_linux_operating_system_name\.”

Let me know in the comments what you find when you try it.

--- ---