SSH Key Overview

SSH is used as the protocol and tool for project developers (members) to access various SourceForge.net developer services:

• Project web access
• Developer web access
• Project uploads
• Subversion access
• Git access
• Mercurial access

To access our services via SSH, you must be a project member (developer), have any needed project permissions enabled for the type of access desired, and have an SSH Client setup.

To avoid the need to use your SourceForge.net password every time you commit, you can set up an SSH key.

SSH Key Types

Over the years, SSH (both the protocol and tools that use the protocol) has been redesigned several times. Each major revision supports a different authentication style and key formats.

• SSH1 protocol and RSA & DSA keys are old and not recommended for the best security.
• ED25519 or ECDSA keys are recommended
• SourceForge.net supports both newer and older key types
• To work with our systems, keys must be formatted in an OpenSSH-compatible key file format; both PuTTY and OpenSSH use a compatible file format. Users of other clients may need to convert their key data for use with our services.

Your SourceForge SSH key data is managed using the links from the Account Services page on the SourceForge.net site.

Protecting your SSH Private Key

Each SSH key pair has a public key component and a private key component. With your public key, a server can identify that a connection comes from a machine that has the private key. Always protect your private key.

Only public key data should ever be uploaded to SourceForge.net.

SSH Clients

To use ssh, you'll need an SSH client, Windows, OSX, and Linux include OpenSSH, Windows users can also use:

• PuTTY and
• WinSCP provide GUI-driven support for SSH (used for interactive login), SCP, and SFTP (used for file transfers).

Key Generation: OpenSSH

To generate an SSH key using OpenSSH:

Run the ssh-keygen command as shown in the following example. Be sure to enter a password for the key to make your key much more secure; omit this passphrase if the key will be used to perform automated (scripted) operations. Replace USERNAME with your SourceForge.net username. If your version of ssh does not support "ed25519" key types, replace "ed25519" with "rsa".

$ ssh-keygen -t ed25519 -C "USERNAME@shell.sf.net"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/username/.ssh/id_ed25519): 
Enter passphrase (empty for no passphrase): ************
Enter same passphrase again: ************
Your identification has been saved in /home/username/.ssh/id_ed25519.
Your public key has been saved in /home/username/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:5vyztOqQaDMFs6eBwYnAxDWxpfgic9nGW5bEDckM56Q USERNAME@shell.sf.net
The key's randomart image is:
+--[ED25519 256]--+
|=..+o=+.         |
|.=..=*+o         |
|..+oE + .        |
|  .* = .         |
|o.+.* * S        |
|.o.. X =         |
|    B o o .      |
|   . o . o..     |
|       .o.+o     |
+----[SHA256]-----+

Key Generation: PuTTY

To generate an SSH key using PuTTY:

1. Execute the PUTTYGEN.EXE program.
2. Select the desired key type, "ED25519", within the "Parameters" section. If ED25519 is not available in your version of Putty, choose ECDSA or RSA.
3. Click on the "Generate" button.
4. Follow the instruction to move the mouse over the blank area of the program to create random data used by PUTTYGEN to generate secure keys. The key generation will occur once PUTTYGEN has collected sufficient random data.
5. Enter USERNAME@shell.sourceforge.net for the key comment, depending on what host the key is for, replacing USERNAME with your SourceForge.net username.
6. Enter the desired passphrase in the "Key passphrase" and "Confirm passphrase" fields. If the key will be used to automate operations (i.e., as part of a script), you may choose to omit this step from the key generation process.
7. Click on the "Save private key" button. Use the resulting dialog to save your private key data for future use. You may use a filename such as SourceForge-Shell.ppk". The .ppk extension is used for PuTTY Private Key files.
8. Go to the SSH key posting page on the SourceForge.net site. Copy your public key data from the "Public key for pasting into OpenSSH authorized_keys2 file" section of the PuTTY Key Generator, and paste the key data to the provided form on the SourceForge.net site. Click on the "Update" button to complete the posting process.
9. Exit the PuTTY Key Generator (PUTTYGEN).

SSH Key Posting

Links to manage your SSH keys may be found on the Account Services page.

Each account on SourceForge.net uses one set of keys for project shell and code repository services.

OpenSSH users will paste the contents of their id_ed25519.pub file (or id_rsa.pub for RSA) -- note the .pub extension on the files that store the public key data. Private key data should never be uploaded.

PuTTY users will paste the contents of the "Public key for pasting into OpenSSH authorized_keys2 file" section of the PuTTY Key Generator (PUTTYGEN.EXE), after loading their key, to the provided key posting form on the site.

Using Multiple SSH Keys

If you have configured your SSH key without a passphrase (to permit automation of operations over SSH), you should only use that key from the hosts performing the automated operations; generate a second key for use from machines used interactively. You may keep multiple SSH keys on file for each account to provide secure access to your account from various hosts. When uploading your SSH key data, one line should be used for each SSH key. Removing an entry in the upload form will remove it from your list of keys; this is the means provided to remove deprecated key data from our servers.

Should you need to use an alternate filename for the key (aside from the default), specify which key you wish to use. With PuTTY and Pageant, this is not a problem. For users of the OpenSSH client, the '-i' flag must be used to specify the key file to be used for authentication. An example follows:

# Replace KEYFILE with the path and filename of the SSH private key to be used
$ ssh -i KEYFILE USERNAME@shell.sourceforge.net

Invalidating Unused Keys

You should only keep keys on file with SourceForge.net if they are actively being used. Disused keys should be removed from your SSH key profile on the SourceForge.net site. To invalidate an SSH key, access the SSH key management page from the Account Settings page and re-post the keys you want to continue using (leave out the key you want to invalidate).

SSH Key Passphrase Usage

SSH clients such as PuTTY and OpenSSH allow you to set a passphrase on your SSH private key. If a passphrase is set on your private key, the SSH client will ask you to enter that passphrase to unlock the private key before it allows you to connect to a remote host using that key. This is added security to prevent someone from assuming your identity if they were to steal your SSH private key. This passphrase is used by your SSH client to unlock your key data and is not transmitted over the wire.

SourceForge.net encourages you always to place a passphrase on your SSH private keys unless the key is being used from a single, secure machine in an automated application (such as launching a backup of project web content each night).

To change or set a passphrase on an SSH key under PuTTY, do the following:

1. Run the puttygen.exe program.
2. Click on the "Load" button.
3. Select the private key file you want to put a passphrase on.
4. Enter the new desired passphrase in the "Key passphrase" and "Confirm Passphrase" fields.
5. Click on the "Save private key" button. Overwrite the existing copy of your key.

To change or set a passphrase on an SSH key under OpenSSH, do the following:

$ ssh-keygen -p -t ed25519
Enter file in which the key is (/home/username/.ssh/id_ed25519): 
Key has comment 'USERNAME@shell.sf.net'
Enter a new passphrase (empty for no passphrase):
Enter the same passphrase again:
Your identification has been saved with the new passphrase.

SSH Agent Overview

SSH agents provide a mechanism for loading an SSH key and providing the associated passphrase. The SSH agent will then automatically respond to authenticating to a remote host.
The benefit of this is that once the key has been loaded into the SSH agent, a passphrase will not have to be entered each time a connection is made.
This makes it a lot more convenient when doing repetitive SSH operations such as code commits. Both the PuTTY suite and OpenSSH provide SSH agents, pageant, and ssh-agent, respectively.

SSH Agent: Pageant

Pageant is the graphical SSH agent provided with the PuTTY SSH Suite. This SSH agent offers convenience for applications such as accessing the shell server using plink.exe or putty.exe. To load a key into pageant for use, do the following:

1. Start Pageant and provide it with the key name 'pageant.exe PATH_TO_SSH_KEY', where PATH_TO_SSH_KEY is the path and filename of the SSH key generated using puttygen.
2. Enter the passphrase if prompted for it in the 'Pageant: Enter Passphrase' box that will come up if a passphrase is associated with the key.
3. Additional keys can be added to Pageant using the dialog options on the pageant interface. Pageant is accessible from the Windows systray.

SSH Agent: ssh-agent

The ssh-agent is provided with OpenSSH. This agent is typically started by default in most environments. If it is not, you may want to refer to platform-specific documentation on how to get the ssh-agent to load on system boot. Adding a key for the ssh-agent to use is done using the ssh-add utility that will prompt you for the key passphrase after loading a key with an associated passphrase. Use of the ssh-add client to add SSH keys to ssh-agent as follows:

# Add the default keys to ssh-agent. If no filenames were specified during key creation, it'd be one of the defaults
ssh-add
# Add a key to ssh-agent that isn't one of the default key files
ssh-add FILENAME

Copying SSH Data Between Hosts

As SourceForge.net permits you to have multiple keys (even of the same type) on file for your account, there is typically little reason to copy SSH key data between different hosts. We encourage you to maintain a separate key for each of your hosts (to minimize security impact).

SSH key data may be backed up and restored if you reload your workstation, or you may generate a new SSH key and invalidate your old key. If you decide to generate a new SSH key remember to invalidate any disused keys.

Backing Up SSH Key Data

You are solely responsible for ensuring you have a viable backup of your SSH key data. Backups of SSH key data should be treated with the same level of security and paranoia that you treat SSH key data on your workstation. Security should be the first and last thing you consider when backing up security data.

Backups of your SSH key data may not be necessary; if your SSH key is lost, generate a new one and invalidate the old one. If you decide you want to backup your SSH key data, make sure your backup is stored securely.

OpenSSH users should backup the contents of the .ssh subdirectory of their home directory on their workstation (not on the shell server).

PuTTY users should backup their key data.

Backups should not be shared between users; if a key is lost, invalidate the old key and generate/upload a new key to replace the lost key.

Example SSH Key Data

Sample ED25519 public key data:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNX4772O/UW3TdoMK/kCxJSbqcGlVO95HmYOQ0B/pAK USERNAME@shell.sourceforge.net

Sample RSA (SSH2) key data (data is on one line, typically, but has been broken here for your viewing convenience):

ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAyyA8wePstPC69PeuHFtOwyTecByonsHFAjHbVnZ+h0dp
omvLZxUtbknNj3+c7MPYKqKBOx9gUKV/diR/mIDqsb405MlrI1kmNR9zbFGYAAwIHGxt0Lv5ffwaqsz7
cECHBbMojQGEz3IH3twEvDfF6cu5p00QfP0MSmEi/eB+W+h30NGdqLJCziLDlp409jAfXbQm/4Yx7apL
vEmkaYSrb5f/pfvYv1FEV1tS8/J7DgdHUAWo6gyGUUSZJgsyHcuJT7v9Tf0xwiFWOWL9WsWXa9fCKqTe
YnYJhHlqfinZRnT/+jkz0OZ7YmXo6j4Hyms3RCOqenIX1W6gnIn+eQIkw USERNAME@shell.sourceforge.net

SSH key data should not be modified during the upload process; do not add any line feeds or spaces to your key data during the upload process.

If your key was created by some other SSH suite, you may have to convert the key format to the OpenSSH key format.

Lost SSH Keys

If you lose your SSH private key data, take steps to invalidate that key via the SSH key management facility immediately. Regenerate and post a replacement SSH key, if needed. If your key was compromised, take immediate action to notify the other members of your development team and verify the integrity of your project data.

Regenerating Lost Public SSH Key

SSH public keys can be regenerated if lost if the private key is available. The reverse is impossible, and a new key pair must be generated if the private key is lost.

OpenSSH: The '-y' option of the ssh-keygen binary can print the public key that corresponds to a given private SSH key:

$ ssh-keygen -t ed25519 -y
Enter file in which the key is (/home/username/.ssh/ed25519):
Enter passphrase:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDNX4772O/UW3TdoMK/kCxJSbqcGlVO95HmYOQ0B/pAK

PuTTY: The PUTTYGEN.EXE program will display the corresponding public SSH key to a given private SSH key when you load the private SSH key into it. The following steps will work for this purpose:

1. Run PUTTYGEN.EXE
2. Click on the 'Load key' button
3. Select the file that contains the private key that you want the associated public key of
4. Enter the passphrase for the private key, if prompted
5. The matching public key will be displayed in the 'Public key for pasting into OpenSSH authorized_keys2 file' section of the PuTTY Key Generator and may also be saved to a file using the provided button.

Conversion from other key formats (ssh.com)

Both OpenSSH and PuTTY include mechanisms in their key generator tools to convert keys from other formats to the OpenSSH key format. SourceForge.net uses the OpenSSH key format. However, some users of unsupported SSH clients may still wish to connect to SourceForge.net using a familiar SSH client. However, please note that we still strongly urge you to use a unique SSH key for each host that you connect to.
To convert the key type, do the following (KEYFILE is the filename and path for the SSH private key that is to be converted):

OpenSSH: The ssh-keygen utility will convert a key file from many formats to the OpenSSH format, including from the SECSH Public Key File Format used by several commercial SSH implementations:

ssh-keygen -i -f KEYFILE

PuTTY: PUTTYGEN.EXE can import and convert some key file formats to the proper type. Follow these steps to do so:

1. Run PUTTYGEN.EXE
2. Select the 'Import key' option from the 'Conversion' menu
3. Select the private key that is to be imported, then click the 'Open' button
4. At this point, you can save the key to the PuTTY .ppk format, and the public key can either be copied and pasted from the interface or saved to a file as needed

Reporting SSH Key Issues

If the above tips don't help resolve your key issue, you should report the matter to SourceForge.net Support. We may ask you for information regarding your key during the issue resolution process, including a copy of the public key data or a key fingerprint. This information can be safely provided in the open without concern as this information is meant to be publicly available and in no way compromises the security of your account. We will, however, never ask for a copy of your SSH private key. You should never provide that key to us or upload it to our hosts.