In this post, we will demonstrate how to generate an SSH key that can be used to authenticate with a Git server.
1. Introduction
The two transfer protocols that are used to access a Git server are HTTPS and SSH (short for Secure Shell). (The git and local protocols are unusable for any but the most basic development environments.) HTTPS uses a username and password for authentication. SSH uses public-key cryptography for authentication and data encryption. SSH is commonly used when a system or process (for example, a build server) requires access to a Git repository.
Public-key cryptography uses a public and private key. The public key is stored on the server and the private key is stored with the client. In this example, we will show how to generate a public and private key pair to use for SSH authentication with a Git server.
1.1 Tools Used in this Example
- Git 2.17
Git downloads are available here: https://git-scm.com/downloads.
Note: This example was created on the macOS Sierra platform. Git for Windows includes Git Bash and Git CMD shells to run command-line operations.
2. Git Generate SSH Key Example
2.1 Check for Existing SSH Keys
Before you generate an SSH key pair, you may want to check if one already exists. The private key file is named id_rsa (if you are using RSA cryptography) and the corresponding public key file is named id_rsa.pub. Since SSH keys are stored in a directory named.”/ssh” by default, you can check for their existence by opening a terminal and running the ls command:
$ ls ~/.ssh
If you have an existing SSH key pair and would like to use these keys to access the Git server, skip down to the “Copy the Public Key to the Server” section below.
2.2 Generate the SSH Keys
If the key files do not exist, you can generate them with the following command:
$ ssh-keygen -t rsa -b 4096
The -t option specifies the algorithm that is to be used for key generation. Options include RSA, DSA, and ECDSA. The -b option specifies the key file size in bits.
(For a complete list of options, visit https://docstore.mik.ua/orelly/networking_2ndEd/ssh/appb_07.htm.)
Executing the command will prompt you for the name and location of the key file.
ssh-keygen – Prompt for Key Name and Location
$ ssh-keygen -t rsa -b 4096 Generating public/private rsa key pair. Enter file in which to save the key (/Users/gilbertlopez/.ssh/id_rsa):
Hit “Enter” to accept the default.
Next, you will be prompted for a passphrase. Using a passphrase will add an extra layer of security. Hit “Enter” for no passphrase. Otherwise, you will be prompted to verify the passphrase that you entered.
ssh-keygen – Prompt for Passphrase
Enter passphrase (empty for no passphrase): Enter same passphrase again:
Note: If you opt to use a passphrase, it is suggested that you add the SSH key to the ssh-agent helper program so that you supply the passphrase once, as opposed to entering it every time you connect to the server. See the section on “Adding the Key to the SSH Agent” for more information.
When key generation has completed, you will see something similar to the following:
Key Generation Output
Your identification has been saved in /Users/gilbertlopez/.ssh/id_rsa. Your public key has been saved in /Users/gilbertlopez/.ssh/id_rsa.pub. The key fingerprint is: SHA256:zpU9W7hPapMRkLvBktDEr8NqMx29uXZDRuIZTJaDghs gilbertlopez@Gilberts-MBP The key's randomart image is: +---[RSA 4096]----+ | . +.. o | | E o + B | | o o B + | | . o Ooo. | | .S=oB+.. | | o=.= += | | ooo =oo. | | = . + *+ | | . o ..+.o. | +----[SHA256]-----+
As you can see, the ssh-keygen command produces the two keys needed for SSH authentication: your private key ( id_rsa ) and a public key ( id_rsa.pub ).
2.3 Copy the Public Key to the Server
If your team has a personal Git server that is configured to accept SSH connections, the public key must be copied to that server and added to the “authorized_keys” file. This can be accomplished with the ssh-copy-id tool. Use the following command:
$ ssh-copy-id user@host
Note: You will be prompted for the passphrase if you selected one during key generation.
Example ssh-copy-id Command Output
$ ssh-copy-id git@192.168.1.xx /usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/Users/gilbertlopez/.ssh/id_rsa.pub" /usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed /usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys Password: Number of key(s) added: 1 Now try logging into the machine, with: "ssh 'git@192.168.1.xx'" and check to make sure that only the key(s) you wanted were added.
The ssh-copy-id command looks for the default identity’s public key (id_rsa.pub or id_dsa.pub) in the users /.ssh directory. If you have more than one key and/or have your key files in a different directory, you must specify it using the -i option. For example:
ssh-copy-id -i ~/.ssh/tatu-key-ecdsa user@host
The ssh-copy-id command also uses the default port for SSH connections, namely port 22. You can specify a different port using the –p option.
Note: If the Git server does not have an authorized_keys file, the ssh-copy-id command will create it.
Next, verify that the key was properly installed on the server. Use the ssh command to connect to the server:
$ ssh 'user@host'
For example:
$ ssh 'git@192.168.1.xx' Enter passphrase for key '/Users/gilbertlopez/.ssh/id_rsa': GilbertopezsMBP:~ git$ '
Many organizations use GitHub or Bitbucket to host and manage their repositories. Visit the following pages for instructions on adding an SSH key to your account.
Github: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
2.4 Adding the Key to the SSH Agent
(Note: This step is optional.)
If you would like to forgo entering your passphrase every time you want to connect to the Git server (and who wouldn’t!), you can add your private key to the ssh-agent helper program. The ssh-agent program manages private keys and their corresponding passphrases. To add the your private key to ssh-agent, use the following command:
$ ssh-add
Example ssh-add Command Output
$ ssh-add Enter passphrase for /Users/gilbertlopez/.ssh/id_rsa: Identity added: /Users/gilbertlopez/.ssh/id_rsa (/Users/gilbertlopez/.ssh/id_rsa)
The ssh-add command looks for the default identity’s public key (id_rsa.pub or id_dsa.pub) in the users /.ssh directory. If you have more than one key and/or have your key files in a different directory, you must specify it. For example:
$ ssh-add ~/directory/filename
You can now connect to the server without being prompted for a passphrase.
3. Summary
In this example, we demonstrated how to generate an SSH key that can be used to authenticate with a Git server. We also showed how to copy the public key to the server and how to add the key to the SSH agent helper program.
