SSH: Connecting to GitHub

Photo credit: https://atulhost.com/how-to-connect-to-an-ssh-server

Hello everyone! Today we will be talking about using SSH to interact with your GitHub projects from the command line. The following will be our goals for today:

• What are SSH keys
• Prepping your local machine to interact with Git/GitHub
• Creating SSH keys with a password
• Sharing SSH public key on GitHub
• Testing SSH connection to GitHub
• Cloning your GitHub repository to your local machine
• Remediating Potential Issues

What are SSH Keys?

SSH keys are a mechanism to authenticate to a remote server/workstation and communicate over an encrypted channel on port 22. It’s largely used for remote administration, transferring files etc. They come in a pair, Private Key and a Public Key. The public key will have the extension .pub. The public key is what you will share with the server you want to connect to, in this case, GitHub. The private key you must NEVER share, else you will let others have unfettered access to your private files.

Prepping your local machine to interact with Git/GitHub

Firstly you must be familiar with some git commands in order to proceed. If you are not, check out this awesome tutorial written by George Seif. Sometimes I forget a number of commands and I always reference his post to re-acquaint myself with a number of them: A full tutorial on how to use GitHub

Creating SSH Keys

Before you clone your remote repository to your local repository, we must first create the ssh key pair. I don’t want to beat a dead horse, but I must emphasize — if you are not familiar with the git environment, please reference the article linked in the previous paragraph.

Ensure that your ~/.ssh directory is present, if not, create it. And then move to that directory. I have demonstrated both on one line below.

sudo mkdir ~/.ssh; cd ~/.ssh

Create two files in this directory — known_hosts and config files, we will need these later.

Now generate your ssh key pair, name it and give it a password. I will be using RSA as the encryption method. It will then ask you to name the key by asking “Enter file in which to save the key”. Leaving it blank, the names will default to id_rsa for the private key and id_rsa.pub for the public key. In the example, I used “dans-macbook”, change to reflect your name.

ssh-keygen -t RSA -C "dans-macbook"

It will then ask you to set a password for the keys. Leave it blank to not set a password, but I highly recommend you do. Now list the contents of the directory. You should see two keys: dans-macbook and dans-macbook.pub. Picture below for reference.

Pictured here are the ssh keys I generated

SSH Config File

Because we used a custom name, dans-macbook, we must specify the name change in the config file. Open the config file with your editor of choice and input the following line, specifying your private key:

IdentityFile ~/.ssh/dans-macbook

Share Public Key with GitHub

To share your public key with GitHub, log on to your GitHub account and go to Settings -> SSH and GPG Keys

Select New SSH key. Fill in the details for your public key. Give it the same name as your public key for consistency, leave the default authentication key and paste in the contents of your public key:

Now it’s time to test your SSH connection to GitHub! In the terminal type the following:

ssh -T git@github.com

If you received the below message, congrats you’ve successfully configured your SSH keys with GitHub! Else, remove the keys you created, remove the private key from the config file and follow through the steps once more.

Cloning Your Repository

With those pre-requisites out of the way, we can now proceed to clone our projects GitHub repo into the directory you initialized earlier with git init.

Head to your project’s GitHub page.

1. Select the Code, green button
2. Ensure to select SSH, not HTTPS!! It will not work otherwise!
3. Copy the SSH address

Back in your terminal issue the following command and paste in your projects SSH address you just copied.

git clone git@github.com:datboyblu3/Purple-Team-Project.git

You should have output similar to the below, if so congrats you are now ready to officially begin working on your project!

Remediating Potential Issues

If you’ve received the following error message….”Error: Permission denied (publickey)”, the server is rejecting your connection. There could be a few reasons why.

1. Verify you’re connecting to the correct server

ssh -vT git@github

Here we are connecting again but requesting more verbosity. The results are as follows:

> OpenSSH_8.1p1, LibreSSL 2.7.3
> debug1: Reading configuration data /Users/YOU/.ssh/config
> debug1: Reading configuration data /etc/ssh/ssh_config
> debug1: /etc/ssh/ssh_config line 47: Applying options for *
> debug1: Connecting to github.com port 22.

2. Ensure your SSH keys are being used.

# start the ssh-agent in the background
$ eval "$(ssh-agent -s)"
> Agent pid 59566
$ ssh-add -l -E sha256
> 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA)

Via GitHub…”Ensure your private key generated and is loaded into SSH. The ssh-add command should print out a long string of numbers and letters. If it does not print anything, you will need to generate a new SSH key and associate it with GitHub”.

3. Verify the public key is associated/attached to your account

Open your terminal and issue the following commands and compare the results of your fingerprint with the public key on your GitHub page:

eval "$(ssh-agent -s)"
> Agent pid 59566

$ ssh-add -l -E sha256
> 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA)/id_rsa (RSA)

4. Github permission denied: ssh add agent has no identities

In summary, when ssh-add-l returns “The agent has no identities”, it means that keys used by ssh (stored in files such as ~/.ssh/ida_rsa etc) are either missing, they are not known to the ssh-agent, which is the authentication agent, or that their permissions are set incorrectly (for example, world writable).

If your keys are missing or if you have not generated any, use ssh-keygen -t rsa, then ssh-add to add them.

If keys exist but are not known to ssh-agent (like if they are in a non-standard folder), use ssh-add /path/to/my-non-standard-ssh-folder/id_rsa to add them.

Thank you for taking the time to read through my article, I hope it was beneficial to you! If you have any questions or comments or need further help, please don’t hesitate to reach out!