Add a New SSH Key To Your Mac

gist-mac-add-ssh-key.md

Add an SSH Key on a Mac

Add and configure an SSH Key to connect to remote source code repositories (like GitHub) and servers.

⚙️ You can use an automated script to add an SSH Key to your Mac.

I use a GitHub repository mac-setup for my basic Mac setup scripts including one to add a new SSH Key.

If you'd like, you can use my repository to add your new SSH Key.

Just follow the PREREQUISITES and then Add an SSH Key of my GitHub repository

🛑 Once you add your new SSH Key to your Mac, you will still need to determine how to add the new public SSH Key to your remote server yourself.

---

Add an SSH Key on a Mac Manually

Here are the steps if you prefer to create and add a new SHH Key manually.

🙇 This is pretty much from the GitHub Documentation on Connecting to GitHub with SSH

The overall process is...

1. Determine if you already have an SSH Key that you want to use
2. If not, generate a new SSH Key
3. Add your SSH Key to your SSH Config
4. Add your SSH Key to the SSH Agent
5. Add your public SSH Key to the host where you want to connect
6. Test the SSH connection

You will then need to add your public portion of your SSH Key to where you are connecting like GitHub or your servers.

TL;DR:

1. Generate the key...

   ssh-keygen -t ed25519 -C "[email protected]"

2. Add your SSH Key to your ~/.ssh/config file...

   Host github.com
     AddKeysToAgent yes
     UseKeychain yes
     IdentityFile ~/.ssh/id_ed25519
   

3. Add your SSH Key to the SSH Agent

   env APPLE_SSH_ADD_BEHAVIOR=macos ssh-add -K ~/.ssh/id_ed25519

---

Determine Your SSH Keys

Your SSH Keys should be located (even if by softlink) in your ~/.ssh directory. To see what keys you have, simply list the files in this directory.

ls -al ~/.ssh

They look something like this...

-rw-------   1 someuser  staff   464 Sep  3 14:41 id_ed25519
-rw-r--r--   1 someuser  staff   103 Sep  3 14:41 id_ed25519.pub

🙇 Checking for existing SSH Keys

---

Generate a New SSH Key

📧 You will need the email address that you want to be associated with your new SSH Key

Encryption Algorithms

On Mac, you can generate the following types ( -t) of SSH Keys (these are the encryption algorithms)...

• dsa
• ecdsa
• ecdsa-sk
• ed25519
• ed25519-sk
• rsa

The ed25519 algorithm is recommended.

Encryption Level (Bits)

You can specify the bit level of encryption using the -b option (e.g. -b 4096 )

Generate

Here the ed25519 algorithm is being used...

1. In a terminal window, run the ssh-keygen command substituting your email for "[email protected]"

   ssh-keygen -t ed25519 -C "[email protected]"

2. When prompted to "Enter a file in which to save the key," You can press Enter to accept the default file location

3. When prompted to "Enter passphrase (empty for no passphrase)," You can press Enter to select no passphrase

4. When prompted to "Enter same passphrase again:," You can press Enter to again select no passphrase

5. When the command finishes, you can verify that it was created by listing your ~/.ssh directory

   ls -al ~/.ssh

🙇 Generating a new SSH Key

---

Add your SSH Key to your SSH config

1. Ensure that you have an ~/.ssh/config file

   touch ~/.ssh/config

2. Edit your ~/.ssh/config file using your preferred editor

3. Add the following lines replacing github.com on the Host line to the hostname where you are connecting and ~/.ssh/id_ed25519 with the filename of your IdentityFile (which is your new generated SSH Key)...

   Host github.com
     AddKeysToAgent yes
     UseKeychain yes
     IdentityFile ~/.ssh/id_ed25519
   

   🍎 macOS Sierra 10.12.2 or later, requires specifying in your ~/.ssh/config file to automatically load keys into the ssh-agent and store passphrases in your keychain

4. Save your ~/.ssh/config file with these changes

---

Add your SSH Key to the SSH Agent

You need to add your new SSH Key to the SSH Agent and your passphrase to the macOS Keychain (if you added a passphrase to your SSH Key)...

1. In a terminal window, run the ssh-add command substituting your new SSH Key file for ~/.ssh/id_ed25519

   env APPLE_SSH_ADD_BEHAVIOR=macos ssh-add -K ~/.ssh/id_ed25519

   ✨ The env APPLE_SSH_ADD_BEHAVIOR=macos environment variable suppresses the warning messages about the -K option being deprecated in newer versions of macOS. The -K option stores the passphrase in your MacOS Keychain

🙇 [Adding your SSH key to the ssh-agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/ generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent)

---

Add Your Public SSH Key to the Remote Host

You will need to add your SSH Key to the remote host where you want to connect, for example github.com.

You will use the contents of the *.pub version of your new SSH Key file but the process for adding it to the remote host will be unique to that host and/or organization.

• To connect your SSH Key to GitHub, see their documentation Adding a new SSH key to your account

---

Test the SSH Connection

If you are connecting to GitHub and have added your public SSH Key to your GitHub account, here's how you can test your SSH connection...

1. In a terminal window, run the ssh command substituting your remote host for [email protected]

   ssh -T [email protected]

   You should see something like this as a response...

   Hi someuser! You've successfully authenticated, but GitHub does not provide shell access.
   

🙇 Testing your SSH connection