Project:Infrastructure/SSH key guide

From Gentoo Wiki
Jump to:navigation Jump to:search

This (old) guide explains on how to create and use ssh keys to interact with the Gentoo ecosystem.

Key handling

SSH key pairs authenticate developers to the Gentoo Infrastructure. Properly handling these keys is vital to keeping our machines safe. Follow these guidelines:

  • Place any and all private keys only on trusted machines. Only the Gentoo developer should have root/super user access on these machines and they are not shared with other users.
  • Do not trust Gentoo Infrastructure. Do not place copies of private keys on Gentoo machines (like
  • Developers may forward their SSH agent through Gentoo managed hosts if they have been configured to allow users to agent forward (more on forwarding later.)
  • Encrypt the ssh keys with a strong passphrase.
    • For those having trouble making a passphrase try emerging app-admin/pwgen, and then running pwgen -sB 25
  • Do not access Gentoo infrastructure from untrusted machines such as business kiosks at hotels, internet cafes, or machines at computer conferences. Many of these machines are infected with malware.
  • If you believe your keys were compromised, contact the infrastructure team immediately. You can do this via #gentoo-infra (webchat) or by emailing
  • Official hostkey fingerprints for Gentoo Infrastructure servers are available on the server specifications page.

Creating the SSH keys

First of all, be physically logged on to your own computer. Make sure that no-one will see you typing stuff in, since we are going to type in passphrases and such. So get your pepperspray and fight all untrusted entities until you are home alone.

Now we are going to create our ssh keys, RSA keys to be exact. The key should be at least 2048 bits in length, but 4096 bits is recommended. Log onto your computer as the user that you are going to be using when you want to access Then use the ssh-keygen utility to generate an SSH key pair:

user $ssh-keygen -t rsa -b 4096
Generating public/private rsa key pair.
Enter file in which to save the key (/home/temp/.ssh/id_rsa): ## (Press enter)
Created directory '/home/temp/.ssh'.
Enter passphrase (empty for no passphrase): ## (Enter your passphrase)
Enter same passphrase again: ## (Enter your passphrase again)
Your identification has been saved in /home/temp/.ssh/id_rsa.
Your public key has been saved in /home/temp/.ssh/
The key fingerprint is:
85:35:81:a0:87:56:78:a2:da:53:6c:63:32:d1:34:48 user@examplehost
Please be sure to set a strong passphrase on your private key. Ideally, this passphrase should be at least eight characters and contain a mixture of letters, numbers and symbols.
Do not set an empty passphrase on your ssh key. If infra finds out this is the case; your account will be suspended.

Created files:

user $ls ~/.ssh

You may have more files than this, but the two files listed above are the ones that are really important.

The first file, id_rsa , is your private key. Don't give this to anyone; never decrypt it on an untrusted machine. Gentoo Developers will never ask you for a copy of your private key.

Be very careful which machines you put your private key on. If you have several ( trusted! ) hosts from which you want to connect to, you should copy the id_rsa file to the ~/.ssh directories on those hosts. Trusted machines are machines that only you have root on; these machines are not shared with other users.

The second file, , is the public key. Distribute this file amongst all hosts that you want to be able to access through SSH pubkey authentication. This file should be appended to ~/.ssh/authorized_keys on those remote hosts. Also add it to your local host so you can connect to that one too if you have several boxes.

Adding the SSH key to the box:

user $cat ~/.ssh/ >> ~/.ssh/authorized_keys

Installing the public key on a machine using LDAP authentication for SSH

If you are a new developer, your recruiter will put your first SSH key into LDAP, so that you can login. You can then add any additional SSH keys yourself using the following procedure.
For most of the Gentoo infrastructure, we use LDAP to distribute user information including SSH public keys. On these machines, ~/.ssh/authorized_keys should generally not contain your key.

You should place your public key into LDAP, using perl_ldap, or ldapmodify directly. The Infrastructure LDAP guide describes this in more detail.

Adding the SSH key with perl_ldap on

user $perl_ldap -b user -C sshPublicKey "$(cat ~/.ssh/" <username>
It may take up to 30 minutes for this change to take effect.
Each sshPublicKey attribute must contain exactly one public key. If you have multiple public keys, you must have multiple attributes!

Using keychain

Every time you want to log on to a remote host using SSH public key authentication, you will be asked to enter your passphrase. As much as everybody likes typing, too much is sometimes too much. Luckily, there is keychain to the rescue.

First, install keychain:

root #emerge --ask net-misc/keychain

Now have keychain load up your private ssh key when you log on to your local box. To do so, add the following to ~/.bash_profile . Again, this should be done on your local machine where you work at the Gentoo CVS.

NEVER run keychain or decrypt the private key on an untrusted host.
FILE ~/.bash_profileAdd this to ~/.bash_profile
keychain ~/.ssh/id_rsa
source ${HOME}/.keychain/${HOSTNAME}-sh

The above is for the bash shell. Other shells have their own file to which these instructions can be added, such as ~/.zprofile for zsh.

This page is based on a document formerly found on our main website
The following people contributed to the original document: , Robin Johnson (robbat2) , Alec Warner (antarus) , and nightmorph
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.