SSH Key Tutorial
Intro
What is SSH? How does it work? This post will answer these questions and go over practical examples of how to use SSH on Mac OS X and PC. We will create an SSH tunnel between our local machines and a webhost (in this case siteground.com) and use that tunnel to download a GIT repository of a website.
SSH (Secure Shell) is a cryptographic network protocol that lets you securely send files from one location to another. SSH keys are required when connecting to services like Github, Beanstalk or web servers that require a secure connection. We will go over the details of how these keys are generated and managed later in this post.
SSH Keys can be generated using several different crypto methods such as RSA, DSA and Elliptic Curve. You don’t need to concern yourself with the details of these methods, they are just options that you will select. RSA is the most common and is what we will be using in this demo. On a sidenote, RSA stand for the Rivest-Shamir-Adleman cryptosystem and it is one of the first practical public-key cryptosystems. You can read more about RSA here, it’s pretty interesting.
While the technical aspects of RSA and SSH are very complicated; generating and using these keys is actually pretty simple. That is what we are going to be going over today.
Usually this will all be handled automatically by the software that you are using. For example if you are using a GIT client on your machine (like Tower) and you connect it to Github, when you login using your Github credentials; Github and your GIT client on your machine will silently exchange keys in the background. Bam, done. You never even knew that it happened. However sometime you will need to generate and share these keys manually. For example, if you are creating a secure connection to the cPanel of your web server.
At the most basic level there are two keys, one public and one private. The private key is basically the “master key” that you (or the service you are connecting to) will hold and never give out. The public key is distributed to the person you are trying to connect to. If you are the one generating the keys, you will hold the private and give out the public; and vice versa.
Let’s get into the details of how this actually works on Mac, and then PC.
Generating SSH Keys on Mac
Mac’s have a built in SSH key generator that can be accessed through the terminal (this is very handy, PC’s require 3rd party software). This is because OS X is based on Unix, and this feature is built in to the Unix command line.
Inside the OS X terminal type the following:
ssh-keygen
Modifiers (full list in Glossary):
-t the type of ssh key you would like to generate, typically rsa. So usually we would type the following
ssh-keygen -t rsa
You will get a message asking you where you would like the key to be generated. Hit enter to create the key in the default location.
You will then be prompted for a password. I recommend generating a strong password and saving it in a secure place so you don’t lose it. DON’T LOSE IT! Save it in a password manager like Bitwarden.
Your key will be saved in the listed location
What is up with the randomart image? It exists only so that two keys can be quickly compared with the human eye to see if they match or are different. You probably won’t need to be concerned with this.
Accessing the hidden .ssh folder
So our keys are stored in the folder Users/nicholascoughlin/.ssh
The period in front of SSH indicates that the folder is hidden. To actually see the folder we will need to unhide these files. There are a couple ways to do this.
1: Command Line: Type the following into the terminal
defaults write com.apple.finder AppleShowAllFiles YES
killall Finder
If you want to hide the files again replace YES with NO
2: 3rd party software such as Funter which I actually really like that just gives you a toggle button.
Once you have unhidden the files you will be able to see your .ssh folder.
Generating SSH Keys on PC
On PC you will need to use a 3rd party tool like PuTTY. Siteground has an excellent tutorial on PuTTY here: Siteground: Putty Tutorial.
Generate an SSH key on Siteground.com and the key to your local machine
That covers the basics of generating ssh keys using the terminal in OS X. Next lets try something a little different. Generating a key in the cPanel of a webhost (Siteground) and adding that key to our Mac. We will follow these basic steps.
- Create plain text document with name “id_dsa” in “Home” folder of your MAC
- Login to your cpanel and generate keys via SSH tool
- Copy generated key and paste it into “id_dsa” file
- Run Terminal and enter ssh-add id_dsa
- Run ssh USER@HOST_NAME -p18765 (replace user with your username and host_name with ip of your server)
Lets try to go through these steps and see how we do. The first three steps here are pretty simple so I won’t be going over those. When you have the key pasted into the plaintext file remember that you can name the key whatever you want. So for consistency you may want to name it siteground_ssh or something similar. You will eventually have ssh keys from many different places, so this naming convention can help you keep track of them.
Add the Siteground SSH Key to your local machine
To add the key to your mac type the following command into the terminal
ssh-add name_of_keyfile
For example:
ssh-add .id_dsa
or
ssh-add .siteground_ssh
Remember to only add the period in front of the keyfiles name if the file is hidden. And if the file is hidden, you must remember to add the period.
Finally! We have gotten our computer to recognize that we have a key that was provided to us by our webhost. But now we have a new problem which is that OS X doesn’t think this file is secure enough.
Change permissions for keyfile
I’ve found an article on how to fix this here Stackabuse: How to fix warning unprotected private key file. Let’s run through the process and see if we can get it going.
We will have to:
- Change the permissions for this file, and if that doesn’t work
- Add this file to the .ssh directory which should be more protected, and if that doesn’t work
- Change the permissions of the .ssh directory!
To accomplish #1 we need to change the permissions of the ssh key file using the following command:
sudo chmod <span class="hljs-number">600</span> /path/to/my/key.pem
So here is the log of us giving this an attempt:
Ok! We have now successfully added the SSH key! The next goal is to use this identity to connect to the Siteground server. Our goal will be to download a git repository of our development website.
Download Git repository of website from Siteground.com
Navigate to the Siteground CPanel and then the appropriate SG-GIT menu where you have setup your repository:
And from there you will be able to copy the git clone command
Paste that command into your terminal and you will start copying the repository to your local machine! From there you can add the repository to your GIT management software like GitTower.
Glossary
sudo – Short for “Super User Do” basically allows you to run commands as a super user, or another specific user. More on the sudo command here Linux: Intro to Sudo.
chmod – Short for “Change Mode” modified the permissions of a file or directory. To learn more about chmod go here Simplemachine: Chmod.
ssh-keygen modifiers and commands
ssh-keygen [-q ][-b bits ] –t type [-N new_passphrase ][-c comment ] [-f output_keyfile ]
ssh-keygen –p [-P old_passphrase ][-n new_passphrase ] [-f keyfile ]
ssh-keygen –i [-f input_keyfile ]
ssh-keygen –e [-f input_keyfile ]
ssh-keygen –y [-f input_keyfile ]
ssh-keygen –c [-P passphrase ][-c comment ] [-f keyfile ]
ssh-keygen –l [-f input_keyfile ]
ssh-keygen –B [-f input_keyfile ]
ssh-keygen –D reader
ssh-keygen –U reader [-f input_keyfile ]
-b bits Specifies the number of bits in the key to create. Minimum is 512 bits. Generally 1024 bits is considered sufficient, and key sizes above that no longer improve security but make things slower. The default is 1024 bits.
-c Requests changing the comment in the private and public key files. This operation is only supported for RSA1 keys. The program will prompt for the file containing the private keys, for the passphrase if the key has one, and for the new comment.
-e This option will read a private or public OpenSSH key file and print the key in a `SECSH Public Key File Format’ to stdout. This option allows exporting keys for use by several commercial SSH implementations.
-f filename Specifies the filename of the key file.
-i This option will read an unencrypted private (or public) key file in SSH2-compatible format and print an OpenSSH compatible private (or public) key to stdout. ssh-keygen also reads the `SECSH Public Key File Format’ This option allows importing keys from several commercial SSH implementations.
-l Show fingerprint of specified public key file. Private RSA1 keys are also supported. For RSA and DSA keys ssh-keygen tries to find the matching public key file and prints its fingerprint.
-p Requests changing the passphrase of a private key file instead of creating a new private key. The program will prompt for the file containing the private key, for the old passphrase, and twice for the new passphrase.
-q Silence ssh-keygen Used by /etc/rc when creating a new key.
-y This option will read a private OpenSSH format file and print an OpenSSH public key to stdout.
-t type Specifies the type of the key to create. The possible values are “rsa1” for protocol version 1 and “rsa” or “dsa” for protocol version 2.
-B Show the bubblebabble digest of specified private or public key file.
-C comment Provides the new comment.
-D reader Download the RSA public key stored in the smartcard in reader
-U reader Upload an existing RSA private key into the smartcard in reader
-N new_passphrase Provides the new passphrase.
-P passphrase Provides the (old) passphrase.
Comments
Recent Work
Basalt
basalt.softwareFree desktop AI Chat client, designed for developers and businesses. Unlocks advanced model settings only available in the API. Includes quality of life features like custom syntax highlighting.
BidBear
bidbear.ioBidbear is a report automation tool. It downloads Amazon Seller and Advertising reports, daily, to a private database. It then merges and formats the data into beautiful, on demand, exportable performance reports.